forpublicai/publicai-mcp-server

forpublicai/publicai-mcp-server

Language: Python

License: MIT

Stars: 5

Forks: 5

Open issues: 1

Created: 2025-10-06T14:29:58Z

Pushed: 2025-12-30T07:55:41Z

Default branch: main

Fork: no

Archived: no

README:

Public AI MCP Server

A FastMCP server that provides AI assistants with access to current, community-maintained information and real-time services.

What is Public AI?

Public AI bridges the gap between AI assistants and real-world information. Instead of relying on outdated training data, AI assistants can query this MCP server to access:

• Community-maintained data from wiki.publicai.co
• Real-time APIs for transit, parking, and location services
• Localized resources like crisis hotlines, emergency services, and community information

How It Works

AI Assistant (Claude, etc.)
↓ queries
MCP Server (this repository)
↓ fetches from
├─→ Wiki (community data)
└─→ External APIs (real-time data)

Understanding Wiki Tools vs MCP Functions

This repository contains MCP functions - Python code that AI assistants can call. These functions access two types of data:

1. Wiki-Based Functions (access community-maintained data)

• Read from wiki.publicai.co where community members maintain Wiki Tools
• Wiki Tools = structured data stored using MediaWiki Cargo (database-like tables)
• Examples: Crisis hotlines, BTO launches, community events
• To contribute data: Edit Wiki Tools on the wiki (no coding required)
• To add new tool types: Create new Wiki Tool with Cargo schema on wiki + add MCP function here

2. API-Based Functions (real-time integrations)

• Call external APIs for live data (transit, parking, maps)
• Examples: Swiss transport, Singapore carpark availability
• To contribute: Add Python code to this repository

Example Flow

1. User asks AI a question: "What's the suicide hotline in Singapore?" 2. AI calls MCP function: use_tool(tool="SuicideHotline", country="Singapore") 3. MCP function queries wiki: Reads from SuicideHotline Wiki Tool's Cargo database 4. AI gets current info: Returns verified, community-maintained resources

Available MCP Functions

Wiki-Based Functions

Functions that read community-maintained Wiki Tools from wiki.publicai.co:

list_tools_by_community(community: str)

List all tools available for a specific community.

Example:

list_tools_by_community(community="Switzerland")
# Returns: List of tools tagged with "Switzerland"

use_tool(tool: str, country: Optional[str] = None, region: Optional[str] = None)

Use a Public AI tool. Automatically adapts based on whether the tool has location-specific resources.

For tools with resources (e.g., SuicideHotline):

use_tool(tool="SuicideHotline", country="Singapore")
# Returns: Crisis hotline numbers and resources for Singapore

For tools without resources (e.g., UpcomingBTO):

use_tool(tool="UpcomingBTO")
# Returns: Full page content about BTO launches

API-Based Functions: Swiss Transport

Real-time Swiss public transport information via transport.opendata.ch:

search_swiss_stations(query: str, limit: int = 10)

Search for train, bus, and tram stations.

search_swiss_stations(query="Zürich HB")

get_swiss_departures(station: str, limit: int = 10)

Get real-time departures with delay information.

get_swiss_departures(station="Bern", limit=5)

plan_swiss_journey(from_station: str, to_station: str, via_station: Optional[str] = None, limit: int = 4)

Plan journeys with real-time connections.

plan_swiss_journey(from_station="Zürich HB", to_station="Geneva")

API-Based Functions: Singapore

Location services for Singapore:

get_singapore_carpark_availability()

Get real-time carpark availability data.

get_singapore_carpark_availability()

API-Based Functions: OpenStreetMap

search_osm_nominatim(query: str, limit: int = 10)

Search for locations worldwide using OpenStreetMap.

search_osm_nominatim(query="Eiffel Tower", limit=5)

Installation

Prerequisites

• Python 3.8+
• FastMCP

Setup

1. Clone the repository:

git clone https://github.com/yourusername/pai-mcp-server.git
cd pai-mcp-server

2. Install dependencies:

pip install -r requirements.txt

3. Run the server:

python main.py

The server will start on http://127.0.0.1:8000.

Configuration

Using with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
"mcpServers": {
"publicai": {
"command": "python",
"args": ["/path/to/pai-mcp-server/main.py"]
}
}
}

Environment Variables

Currently, no environment variables are required. Future API integrations may require API keys.

Contributing

Public AI has two contribution pathways:

1. Contribute Data (No Coding Required)

Add or update Wiki Tools on wiki.publicai.co:

• Crisis hotline numbers for your country
• BTO launch information
• Community events and resources
• Verify and update existing data

See: Wiki Contribution Guide

2. Add MCP Functions (Python Required)

Integrate new APIs or build functions that require real-time data:

1. Fork this repository 2. Add your Python file to the functions/ folder 3. Test locally 4. Submit a Pull Request

See: [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines

Example: Adding a New Function

Create a new file in functions/weather.py:

from fastmcp import FastMCP
import json
import urllib.request
from typing import List, Dict, Optional, Any

def register_weather_functions(mcp: FastMCP):
"""Register weather-related MCP functions"""

@mcp.tool()
def get_weather_alerts(country: str, region: Optional[str] = None) -> List[Dict[str, Any]]:
"""Get severe weather alerts for a location.

Args:
country: Country name (e.g., "Singapore", "Switzerland")
region: Optional region/state

Returns:
List of active weather alerts
"""
try:
# Your implementation here
url = f"https://api.weather.service/alerts?country={country}"
with urllib.request.urlopen(url, timeout=10) as response:
data = json.loads(response.read().decode())

return data.get('alerts', [])
except Exception as e:
return…