|
|
| Line 98: |
Line 98: |
| * The information doesn't require API calls | | * The information doesn't require API calls |
| * You need a specific data structure for your use case | | * You need a specific data structure for your use case |
| * Multiple people can verify and update the information
| |
|
| |
|
| '''Step-by-step guide:''' | | '''Quick start:''' |
| | | # Create <code>Template:YourToolNameResource</code> - define your data fields (see [[Template:SuicideHotlineResource]] or [[Template:UpcomingBTOResource]] as examples) |
| '''Step 1: Design Your Resource Template'''
| | # Create <code>Tool:YourToolName</code> - use the {{tl|Tool}} template with <code>has_resources=true</code> |
| | | # Create <code>Resource:YourToolName/Location</code> - add your first resource using your template |
| Create a page: <code>Template:YourToolNameResource</code> | | # Go to [[Special:CargoTables]], find your table, and click "Recreate data" |
| | |
| This template defines what data your tool collects. Each tool has complete freedom to define its own fields!
| |
| | |
| '''Example:''' Library Hours Resource Template
| |
| <pre> | |
| <noinclude> | |
| This template stores library operating hours by location.
| |
| | |
| {{#cargo_declare: | |
| _table=LibraryHoursResources
| |
| |tool=Page | |
| |country=String
| |
| |region=String
| |
| |library_name=String
| |
| |weekday_hours=String
| |
| |weekend_hours=String
| |
| |holiday_hours=String
| |
| |phone=String
| |
| |website=URL
| |
| |last_verified=Date
| |
| }}
| |
|
| |
|
| == Parameters ==
| | '''💡 Important:''' ALL resource templates must include these baseline fields: <code>tool</code>, <code>country</code>, <code>region</code>, <code>last_verified</code>. Your table name must be <code>YourToolNameResources</code> for the MCP server to work. |
| * '''tool''' - The tool page (should be "Tool:LibraryHours")
| |
| * '''country''' - Country name
| |
| * '''region''' - Region/state within country
| |
| * '''library_name''' - Name of the library
| |
| * '''weekday_hours''' - Operating hours Monday-Friday
| |
| * '''weekend_hours''' - Operating hours Saturday-Sunday
| |
| * '''holiday_hours''' - Special holiday hours
| |
| * '''phone''' - Contact phone number
| |
| * '''website''' - Library website URL
| |
| * '''last_verified''' - Date information was verified (YYYY-MM-DD)
| |
| | |
| [[Category:Templates]]
| |
| </noinclude>
| |
| <includeonly>
| |
| {| class="wikitable" style="width:100%;"
| |
| ! colspan="2" | {{{library_name}}} - {{{country}}}{{#if:{{{region|}}}| ({{{region}}})}}
| |
| |-
| |
| | '''Weekday Hours''' || {{{weekday_hours}}}
| |
| |-
| |
| | '''Weekend Hours''' || {{{weekend_hours}}}
| |
| |-
| |
| {{#if:{{{holiday_hours|}}}|
| |
| {{!}} '''Holiday Hours''' {{!}}{{!}} {{{holiday_hours}}}
| |
| {{!}}-
| |
| |}}
| |
| | '''Phone''' || {{{phone}}}
| |
| |-
| |
| | '''Website''' || [{{{website}}} Visit website]
| |
| |}
| |
| | |
| {{#cargo_store:
| |
| _table=LibraryHoursResources
| |
| |tool={{{tool}}}
| |
| |country={{{country}}}
| |
| |region={{{region|}}}
| |
| |library_name={{{library_name}}}
| |
| |weekday_hours={{{weekday_hours}}}
| |
| |weekend_hours={{{weekend_hours}}}
| |
| |holiday_hours={{{holiday_hours}}}
| |
| |phone={{{phone}}}
| |
| |website={{{website}}}
| |
| |last_verified={{{last_verified}}}
| |
| }}
| |
| </includeonly>
| |
| </pre>
| |
| | |
| '''Important note about <code>region</code>:''' Even if your tool doesn't use regions (e.g., it's only for one country), you MUST include the <code>region</code> field in your template. The <code>{{Tool}}</code> template queries all resource tables expecting both <code>country</code> and <code>region</code> fields. You can leave it empty when using the template (e.g., <code>|region=</code>). | |
| | |
| '''Key parts:'''
| |
| * '''<code>_table</code>''': Must be <code>YourToolNameResources</code> (this is important for the MCP server!)
| |
| * '''Required baseline fields''': ALL resource tables MUST include these fields:
| |
| ** <code>tool=Page</code> - The tool page reference
| |
| ** <code>country=String</code> - Country name
| |
| ** <code>region=String</code> - Region/state (can be left empty if not needed)
| |
| ** <code>last_verified=Date</code> - Verification date
| |
| * '''Custom fields''': Add whatever additional fields your tool needs with their types (String, Date, URL, Text, Integer, etc.)
| |
| * '''Display template''': Create a nice visual display for the data
| |
| * '''<code>cargo_store</code>''': Saves the data to the Cargo database (must include all declared fields)
| |
| | |
| '''Step 2: Create the Tool Page'''
| |
| | |
| Create a page: <code>Tool:YourToolName</code>
| |
| | |
| <pre>
| |
| {{Tool
| |
| |name=Library Hours
| |
| |description=Operating hours for public libraries by location
| |
| |community=Singapore
| |
| |has_resources=true
| |
| |resource_table=LibraryHoursResources
| |
| |overview=Provides current operating hours for public libraries, including weekday, weekend, and holiday schedules.
| |
| |usage=Query by library name or location to get current hours. All times are in local timezone.
| |
| }}
| |
| | |
| == About This Tool ==
| |
| | |
| This tool provides up-to-date operating hours for public libraries. Information is maintained by community contributors and library staff.
| |
| | |
| == Contributing ==
| |
| | |
| To add library hours for your location:
| |
| # Create a page: <code>Resource:LibraryHours/YourLocation</code>
| |
| # Use the {{tl|LibraryHoursResource}} template
| |
| # Verify hours from official library websites
| |
| # Update the last_verified date
| |
| | |
| == See Also ==
| |
| * [[Template:LibraryHoursResource]] - Template for adding library hours
| |
| | |
| [[Category:Tools]]
| |
| [[Category:Community]]
| |
| </pre>
| |
| | |
| '''Important fields:'''
| |
| * <code>has_resources=true</code> - Indicates this tool uses resources
| |
| * <code>resource_table=YourToolNameResources</code> - Must match your template's _table name
| |
| | |
| '''Step 3: Create Your First Resource'''
| |
| | |
| Create a page: <code>Resource:YourToolName/Location</code>
| |
| | |
| Use your new template to add the first resource!
| |
| | |
| '''Step 4: Update Cargo Tables'''
| |
| | |
| Critical step - makes your data queryable:
| |
| # Go to [[Special:CargoTables]]
| |
| # Find your new table (e.g., <code>LibraryHoursResources</code>)
| |
| # Click "Recreate data"
| |
| # Your tool is now live!
| |
|
| |
|
| ---- | | ---- |
| Line 284: |
Line 152: |
| ---- | | ---- |
|
| |
|
| == Detailed Examples == | | == Examples to Learn From == |
|
| |
|
| === Example: Adding a Suicide Hotline Resource ===
| | '''Well-designed Tools:''' |
| | | * [[Tool:SuicideHotline]] + [[Template:SuicideHotlineResource]] - Crisis resources with multiple contact methods |
| The [[Tool:SuicideHotline]] uses [[Template:SuicideHotlineResource]] which has fields for:
| | * [[Tool:UpcomingEvents]] + [[Template:UpcomingEventsResource]] - Events with dates and venue information |
| * Multiple phone numbers (primary, secondary, youth hotline)
| | * [[Tool:UpcomingBTO]] + [[Template:UpcomingBTOResource]] - Single-country tool (region field left empty) |
| * Text services (SMS, WhatsApp)
| |
| * Online chat URLs
| |
| * Emergency services
| |
| * Languages supported
| |
| * Operating hours
| |
| | |
| Create a page: <code>Resource:SuicideHotline/YourCountry</code>
| |
| | |
| <pre>
| |
| {{SuicideHotlineResource
| |
| |tool=Tool:SuicideHotline
| |
| |country=United States
| |
| |primary_phone=988
| |
| |primary_phone_description=National Suicide Prevention Lifeline - 24/7 support
| |
| |text_service=Text "HELLO" to 741741
| |
| |text_service_description=Crisis Text Line - 24/7 text support
| |
| |online_chat_url=https://988lifeline.org/chat
| |
| |online_chat_description=Online chat available 24/7
| |
| |languages=English, Spanish
| |
| |availability=24/7
| |
| |additional_info=Free and confidential. Veterans can press 1 for specialized support.
| |
| |last_verified=2025-12-26
| |
| }}
| |
| </pre>
| |
| | |
| === Example: Adding an Upcoming Event ===
| |
| | |
| The [[Tool:UpcomingEvents]] uses [[Template:UpcomingEventsResource]] which has fields for:
| |
| * Event name and type
| |
| * Start and end dates
| |
| * Venue and address
| |
| * Admission details
| |
| * Event description
| |
| * Registration URL
| |
| | |
| Create a page: <code>Resource:UpcomingEvents/Singapore</code>
| |
| | |
| <pre>
| |
| {{UpcomingEventsResource
| |
| |tool=Tool:UpcomingEvents
| |
| |country=Singapore
| |
| |event_name=Singapore Art Week 2026
| |
| |event_type=Cultural
| |
| |start_date=2026-01-10
| |
| |end_date=2026-01-18
| |
| |venue=Multiple locations across Singapore
| |
| |address=Various galleries and museums
| |
| |admission=Mixed (some free, some ticketed)
| |
| |description=Annual celebration of visual arts with exhibitions, talks, and workshops
| |
| |registration_url=https://www.artweek.sg
| |
| |last_verified=2025-12-26
| |
| }}
| |
| | |
| {{UpcomingEventsResource
| |
| |tool=Tool:UpcomingEvents
| |
| |country=Singapore
| |
| |event_name=National Day Parade 2026
| |
| |event_type=National Celebration
| |
| |start_date=2026-08-09
| |
| |venue=Marina Bay Floating Platform
| |
| |admission=Free (ballot required)
| |
| |description=Singapore's National Day celebration with parade and fireworks
| |
| |last_verified=2025-12-26
| |
| }}
| |
| </pre>
| |
| | |
| Note: You can add multiple resources to the same page!
| |
| | |
| === Example: Adding BTO Launches (Single-Country Tool) ===
| |
| | |
| The [[Tool:UpcomingBTO]] uses [[Template:UpcomingBTOResource]] which has fields for:
| |
| * Launch month
| |
| * Location (estate/area)
| |
| * Unit count
| |
| * Flat types (2R, 3R, 4R, etc.)
| |
| * Classification (Standard/Plus/Prime)
| |
| | |
| This is an example of a '''single-country tool''' - it only applies to Singapore. Even though it doesn't use the <code>region</code> field, the field must still exist in the template schema. We simply leave it empty when creating resources.
| |
| | |
| Create a page: <code>Resource:UpcomingBTO/Feb2026</code>
| |
| | |
| <pre>
| |
| {{UpcomingBTOResource
| |
| |tool=Tool:UpcomingBTO
| |
| |country=Singapore
| |
| |region=
| |
| |launch_month=February 2026
| |
| |location=Bukit Merah
| |
| |unit_count=1040
| |
| |flat_types=2R Flexi, 3R, 4R
| |
| |classification=Prime
| |
| |last_verified=2025-12-26
| |
| }}
| |
| | |
| {{UpcomingBTOResource
| |
| |tool=Tool:UpcomingBTO
| |
| |country=Singapore
| |
| |region=
| |
| |launch_month=February 2026
| |
| |location=Tampines (near MRT)
| |
| |unit_count=800
| |
| |flat_types=3R, 4R, 5R
| |
| |classification=Standard
| |
| |last_verified=2025-12-26
| |
| }}
| |
| </pre>
| |
| | |
| Notice: <code>|region=</code> is empty but must be included!
| |
|
| |
|
| == How Resource Templates Work == | | == How Resource Templates Work == |
| Line 457: |
Line 217: |
| * Opinion pieces or subjective content | | * Opinion pieces or subjective content |
| * Time-sensitive data that changes by the minute (use MCP tools with APIs instead) | | * Time-sensitive data that changes by the minute (use MCP tools with APIs instead) |
|
| |
| == Technical Documentation ==
| |
|
| |
| === For Developers ===
| |
|
| |
| This wiki uses:
| |
| * '''MediaWiki''': The underlying wiki platform
| |
| * '''Cargo Extension''': Structured data storage and querying
| |
| * '''FastMCP Server''': Exposes wiki data as MCP tools for AI assistants
| |
|
| |
| '''Repository:''' [https://github.com/forpublicai/pai-mcp-server pai-mcp-server]
| |
|
| |
| === How the MCP Server Works ===
| |
|
| |
| The MCP server provides three main functions for wiki tools:
| |
|
| |
| '''1. list_tools_by_community(community)'''
| |
| * Lists all tools available for a community
| |
| * Queries the Tools table
| |
|
| |
| '''2. use_tool(tool, country, region=None)'''
| |
| * Retrieves resources for a specific tool and location
| |
| * Automatically discovers the resource table structure using the Cargo API
| |
| * Works with any tool's custom resource template
| |
| * Example: <code>use_tool("SuicideHotline", "Singapore")</code>
| |
|
| |
| '''3. add_resource(tool, country, resource_data, region=None)'''
| |
| * Adds a new resource to a tool's resource page
| |
| * Validates fields against the tool's resource table schema
| |
| * Safely prepends content without overwriting existing data
| |
| * Example: <code>add_resource("UpcomingEvents", "Singapore", {"event_name": "Art Fair", "start_date": "2026-03-15", ...})</code>
| |
|
| |
| The server uses <code>cargofields</code> API to dynamically discover each tool's schema, so it works with any custom resource template!
| |
|
| |
| === Naming Conventions (Important!) ===
| |
|
| |
| For the MCP server to work correctly with your tool:
| |
|
| |
| * '''Tool page:''' <code>Tool:YourToolName</code>
| |
| * '''Resource template:''' <code>Template:YourToolNameResource</code>
| |
| * '''Cargo table:''' <code>YourToolNameResources</code> (defined in template's <code>_table</code>)
| |
| * '''Resource pages:''' <code>Resource:YourToolName/Location</code>
| |
|
| |
| The server automatically derives table and template names from the tool name, so consistency is critical!
| |
|
| |
| === API Access ===
| |
|
| |
| Data can be queried via:
| |
| * '''MediaWiki API''': Standard MediaWiki API endpoints (<code>https://wiki.publicai.co/w/api.php</code>)
| |
| * '''Cargo API''': Query structured data using <code>action=cargoquery</code>
| |
| * '''Cargo Fields API''': Discover table schemas using <code>action=cargofields</code>
| |
| * '''MCP Server''': FastMCP server provides simplified access for AI assistants
| |
|
| |
| === Cargo Tables ===
| |
|
| |
| View and manage the structured data:
| |
| * [[Special:CargoTables|View all Cargo tables]]
| |
| * '''Tools''' table: Stores all tool definitions
| |
| * '''[ToolName]Resources''' tables: Each tool has its own resource table with custom fields
| |
|
| |
| '''After editing resources:''' Remember to recreate the Cargo table data at [[Special:CargoTables]] to make your changes queryable!
| |
|
| |
| == Need Help? ==
| |
|
| |
| * '''Creating templates''': Study [[Template:SuicideHotlineResource|SuicideHotlineResource]] or [[Template:UpcomingEventsResource|UpcomingEventsResource]] as examples
| |
| * '''Cargo tables''': [[Special:CargoTables|Manage Tables]]
| |
| * '''MCP Server''': [https://github.com/forpublicai/pai-mcp-server GitHub Repository]
| |
| * '''Questions''': Open an issue in the repository or ask in discussions
| |
|
| |
| == Examples to Learn From ==
| |
|
| |
| '''Well-designed Wiki Tools:'''
| |
| * [[Tool:SuicideHotline]] - Crisis resources with rich custom template
| |
| * [[Tool:UpcomingEvents]] - Events with date fields and venue information
| |
|
| |
| '''Well-structured Resources:'''
| |
| * [[Resource:SuicideHotline/Singapore]] - Complete fields, multiple contact methods
| |
| * [[Resource:UpcomingEvents/Singapore]] - Multiple events on one page
| |
|
| |
| '''Good Templates to Study:'''
| |
| * [[Template:SuicideHotlineResource]] - Complex template with many field types
| |
| * [[Template:UpcomingEventsResource]] - Date handling and optional fields
| |
|
| |
|
|
| |
|
| [[Category:Public AI]] | | [[Category:Public AI]] |
Public AI is a structured knowledge base of tools and resources that AI assistants can access programmatically to help users with real-world tasks.
Public AI serves as a bridge between AI assistants (like Claude, ChatGPT, etc.) and real-world information that users need. Instead of AI assistants having outdated or incomplete information, they can query this wiki to get current, accurate, and localized data.
- Structured Data: Information is stored using MediaWiki's Cargo extension, making it queryable like a database
- MCP Server: A FastMCP server reads from this wiki and exposes the data as tools that AI assistants can use
- AI Integration: When you ask an AI assistant a question (e.g., "What's the suicide hotline in Singapore?"), it queries this wiki and gives you current information
- Crisis Support: Get current hotline numbers and resources for mental health emergencies
- Transit Information: Real-time public transportation schedules and routes
- Events & Activities: Discover upcoming community events and festivals
- Location Services: Search for places and get geographic information
- And more...: Any information that benefits from being current, localized, and structured
Understanding Public AI Tools[edit | edit source]
Public AI has two types of tools, each serving different purposes:
| Wiki Tools
|
MCP Tools
|
Data lives in this wiki
The MCP server reads and serves wiki content to AI assistants
|
Code lives in GitHub repository
Python functions that integrate with external APIs
|
| Examples:
|
Examples:
- Swiss Transit - Calls transport.opendata.ch API
- Singapore Carparks - Queries data.gov.sg API
|
| Who can contribute: Anyone (no coding required)
|
Who can contribute: Developers (Python required)
|
Best for:
- Location-specific resources
- Information that changes over time
- Data that needs community verification
- Custom data structures per tool
|
Best for:
- Real-time API integrations
- Complex data processing
- External service connections
|
Choose your contribution pathway based on what you want to do:
1️⃣ Add Data to an Existing Tool[edit | edit source]
Add or update localized data for an existing tool
Difficulty: Easy (no coding required)
Perfect for:
- Adding suicide hotline numbers for your country
- Contributing upcoming events in your region
- Adding local crisis resources
- Verifying and updating existing information
Quick start:
- Browse the tools above and find one with
has_resources=true
- Check the tool's page for its custom resource template (e.g., Template:SuicideHotlineResource, Template:UpcomingEventsResource)
- Create or edit a page:
Resource:ToolName/YourLocation
- Use the tool's specific resource template with the appropriate fields
- Fill in your local data and save!
💡 Tip: Look at existing resources for that tool to see what fields are available and how to format your data.
2️⃣ Create a New Wiki Tool[edit | edit source]
Design a new tool with a custom data structure
Difficulty: Medium
When to use this:
- You have location-specific data that communities can maintain
- The information doesn't require API calls
- You need a specific data structure for your use case
Quick start:
- Create
Template:YourToolNameResource - define your data fields (see Template:SuicideHotlineResource or Template:UpcomingBTOResource as examples)
- Create
Tool:YourToolName - use the Template:Tl template with has_resources=true
- Create
Resource:YourToolName/Location - add your first resource using your template
- Go to Special:CargoTables, find your table, and click "Recreate data"
💡 Important: ALL resource templates must include these baseline fields: tool, country, region, last_verified. Your table name must be YourToolNameResources for the MCP server to work.
Implement a Python tool that integrates with external APIs
Difficulty: Advanced (requires Python/coding)
When to use this:
- You need to call external APIs (weather, transit, etc.)
- The tool requires real-time data
- Complex logic or data transformation is needed
Quick start:
- Fork the repository
- Add your
@mcp.tool() function to main.py
- Test locally with
python main.py
- Submit a Pull Request
Example tools to create:
- Weather API integrations
- Stock market data
- Real-time transit for other countries
- News aggregators
| I want to...
|
Use this pathway
|
| Add data to an existing tool
|
1️⃣ Add Data to an Existing Tool
|
| Create a tool with custom data fields
|
2️⃣ Create a New Wiki Tool
|
| Build an API integration or complex tool
|
3️⃣ Add a New MCP Tool
|
Well-designed Tools:
How Resource Templates Work[edit | edit source]
Each tool defines its own resource template with exactly the fields it needs:
| Tool
|
Template
|
Custom Fields
|
Notes
|
| Tool:SuicideHotline
|
Template:SuicideHotlineResource
|
primary_phone, secondary_phone, text_service, online_chat_url, youth_hotline, emergency_services, languages, availability
|
Multi-country, uses region for states/provinces
|
| Tool:UpcomingEvents
|
Template:UpcomingEventsResource
|
event_name, event_type, start_date, end_date, venue, address, admission, description, registration_url
|
Multi-country, region optional
|
| Tool:UpcomingBTO
|
Template:UpcomingBTOResource
|
launch_month, location, unit_count, flat_types, classification
|
Single-country (Singapore only), region left empty
|
| Your tool!
|
Template:YourToolResource
|
Whatever fields you need!
|
Remember: tool, country, region, last_verified are always required
|
This gives tool creators complete flexibility to structure their data appropriately.
- Accuracy: All information must be current and verified
- Verification: Always include a
last_verified date
- Completeness: Fill in all relevant fields for your resource
- Localization: Information should be specific to the country/region
- Neutrality: Present information objectively without bias
✅ Good candidates for Wiki Tools:
- Information that changes over time (phone numbers, schedules, events)
- Localized data (country/region-specific resources)
- Public services (hotlines, transit, emergency services, events)
- Data that AI assistants frequently need but may not have current info on
- Information that benefits from community verification
❌ Not appropriate:
- Personal or private information
- Copyrighted content without permission
- Information that rarely changes and is well-known (e.g., historical facts)
- Opinion pieces or subjective content
- Time-sensitive data that changes by the minute (use MCP tools with APIs instead)
