GSA MCP Hackathon – Servervorlage

Ein sofort einsatzbereiter Starter zum Erstellen eines Model Context Protocol (MCP)-Servers in Python, plus Bereitstellungskits für IBM Cloud (watsonx Orchestrate) und Databricks.

Erstellt mit FastMCP und uv. Wenn Sie noch nie einen MCP-Server erstellt haben, beginnen Sie mit QUICKSTART.md.

Was ist ein MCP-Server?

Ein MCP-Server stellt Tools (Funktionen, die das Modell aufrufen kann), Prompts (wiederverwendbare Gesprächsstarter) und Ressourcen (Daten, die das Modell lesen kann) für einen KI-Client wie Claude Desktop, Claude Code oder eine Agentenplattform wie watsonx Orchestrate bereit. Sie schreiben die Tools; das Modell des Clients entscheidet, wann es sie aufruft.

Diese Vorlage bietet Ihnen einen funktionierenden Server mit einem Beispiel für jede Art, sodass Sie die Beispiele durch Ihren eigenen Dienst ersetzen und bereitstellen können.

Related MCP server: Python MCP Server Template

Repository-Struktur

mcp-hackathon-template/
├── README.md                  # This file
├── QUICKSTART.md              # 5-minute clone → run → connect walkthrough
├── main.py                    # Local entry point (uv run python main.py)
├── pyproject.toml             # Package + dependencies (uv)
├── requirements.txt           # Mirror of runtime deps (for buildpack hosts)
├── Dockerfile                 # Container image (streamable-HTTP, port 8080)
├── manifest.yaml              # cloud.gov (Cloud Foundry) deploy
├── server.json                # MCP registry metadata
├── .env.example               # Copy to .env for local dev
├── .github/workflows/ci.yml   # Lint + test on push/PR
├── src/
│   └── example_server/        # ← rename to your service
│       ├── app.py             # Thin entry point: builds FastMCP, picks transport
│       ├── config.py          # Settings from env vars / .env
│       ├── models.py          # Pydantic models & enums for tool params
│       ├── utils.py           # Shared helpers (HTTP client, pagination)
│       ├── routes.py          # HTTP-only routes (/health, /version)
│       ├── tools/             # ONE FILE PER TOOL
│       │   ├── __init__.py    #   register_tools(mcp) aggregator
│       │   └── example_tool.py
│       ├── prompts/
│       │   ├── __init__.py    #   register_prompts(mcp) aggregator
│       │   └── example.py
│       └── resources/
│           ├── __init__.py    #   register_resources(mcp) aggregator
│           └── example.py
├── tests/                     # Import + registration smoke tests
├── eval/                      # Stub → build a Phoenix eval harness (see mcp-eval skill)
└── deploy/
    ├── README.md              # Which deployment kit to use
    ├── ibm/                   # watsonx Orchestrate: 3 kits (see below)
    └── databricks/            # Databricks Apps kit

Erste Schritte

Voraussetzungen

• uv – pip install uv oder brew install uv

Installieren und ausführen

cp .env.example .env
uv sync
uv run python main.py

Der Server startet im stdio-Modus – er kommuniziert über stdin/stdout per JSON-RPC, so starten lokale Clients (Claude Desktop, Claude Code) ihn. Siehe QUICKSTART.md, um einen Client zu verbinden.

Überprüfen

uv sync --group dev
uv run pytest tests/ -v      # tests
uv run ruff check .          # lint

Das Muster „Ein Tool pro Datei“

Jedes Tool lebt in einer eigenen Datei unter src/example_server/tools/ und stellt eine register(mcp)-Funktion bereit. tools/__init__.py ruft jede aus einem einzigen register_tools(mcp) auf. Dadurch bleibt die Tool-Liste überschaubar und Sie können eine Integration hinzufügen oder entfernen, indem Sie zwei Dateien anfassen.

Schritt 1 – erstellen Sie src/example_server/tools/my_tool.py:

from typing import Annotated
from fastmcp import FastMCP

from example_server.utils import fetch_json


def register(mcp: FastMCP) -> None:
    @mcp.tool(
        name="example_get_thing",
        annotations={
            "title": "Get a thing",
            "readOnlyHint": True,
            "destructiveHint": False,
            "idempotentHint": True,
            "openWorldHint": True,
        },
    )
    async def get_thing(thing_id: Annotated[str, "The ID to fetch."]) -> dict:
        """One-line summary. Document the data source, its update cadence,
        and the return shape here — the model reads this docstring."""
        return await fetch_json(f"https://api.example.gov/things/{thing_id}")

Schritt 2 – binden Sie es in tools/__init__.py ein:

from example_server.tools import example_tool, my_tool

def register_tools(mcp) -> None:
    example_tool.register(mcp)
    my_tool.register(mcp)  # ← add this line

Schritt 3 – fügen Sie einen beliebigen API-Schlüssel als typisiertes Feld in config.py hinzu und dokumentieren Sie die Umgebungsvariable in .env.example.

Prompts (prompts/) und Ressourcen (resources/) folgen dem exakt gleichen register(mcp)- + Aggregator-Muster.

Paket umbenennen

Bevor Sie Ihren Server veröffentlichen, benennen Sie example_server in Ihren Dienst um (z. B. census_mcp):

1. Benennen Sie den Ordner src/example_server/ in src/<your_name>/ um.

2. Aktualisieren Sie pyproject.toml: den [project].name, die [project].scripts und die [tool.hatch.build.targets.wheel].packages.

3. Suchen-und-ersetzen Sie example_server in src/, tests/, main.py, Dockerfile und manifest.yaml.

Tipps zur Tool-Entwicklung (Bundesdaten)

• Geben Sie strukturierte Daten zurück, keinen Prosa. Geben Sie Dictionaries/Listen mit konsistenten Schlüsseln zurück und lassen Sie das Modell erzählen.

• Dokumentieren Sie die Aktualität. Bundesdatensätze hinken hinterher; geben Sie die Aktualisierungshäufigkeit und das „Stand“-Datum im Docstring an.

• Stellen Sie Paginierung bereit. Verwenden Sie PaginationParams / paginate() aus utils.py und geben Sie has_more / next_offset zurück.

• Verwenden Sie explizite Timeouts. utils.fetch_json hat standardmäßig 30s.

• Umsetzbare Fehler. Geben Sie ein Fehler-Dictionary mit einem hint zurück, keinen rohen Stack-Trace.

Bereitstellung

Die lokale Entwicklung verwendet stdio. Um Ihren Server mit einer Agentenplattform zu teilen, stellen Sie ihn bereit und registrieren Sie ihn. Siehe deploy/README.md für eine Auswahlhilfe, dann:

• IBM watsonx Orchestrate – deploy/ibm/ (drei Kits: lokales stdio-Toolkit, Code Engine build-from-Git und vorgefertigtes Image).

• Databricks Apps – deploy/databricks/.

Beide lesen denselben Servercode; app.py bedient automatisch HTTP, wenn die Plattform einen Port injiziert.

Evaluierungen

Zu messen, wie gut ein LLM Ihre Tools nutzen kann, ist der wahre Test der Serverqualität. Diese Vorlage enthält absichtlich kein Evaluierungs-Framework – siehe eval/README.md für den Bau eines solchen mit der mcp-eval-Fähigkeit.

Lizenz

MIT. Siehe SECURITY.md für die Richtlinie zur Offenlegung von Schwachstellen und die Sicherheitshinweise zum Hackathon.