eswat2-mcp
Personal MCP + REST server — Python + FastMCP + FastAPI + uvicorn, single process on port 9100.
stack
Everything is Python — server, scripts, and tests. No Node.js runtime in the hot path.
@mcp.resource, @mcp.tool)/docsFastAPI at root, FastMCP mounted at /mcp. Port default 9100, configurable via MCP_PORT env var.
mcp = FastMCP("eswat2", instructions="…") # resources + tools registered on mcp… app = FastAPI(lifespan=…) app.mount("/mcp", mcp.http_app()) @app.get("/health") # liveness @app.get("/list_namespaces") @app.get("/list_uris") @app.get("/resolve") # ?uri=namespace://slug
modules/<namespace>/. Each namespace compiles to kbs/<namespace>-kb.json via task build. The server reads only the compiled KB files at runtime. Always run task build before deploying.
color-picker-v8, icon-gallery-005 that LLMs discover and use via the Vercel deploymentAll content addressed as namespace://slug — e.g. profile://biography, specs://color-picker-v8, art://syd-mead-running-six.
The server manifest at eswat2://manifest lists every available URI across all namespaces — an LLM's starting point.
Claude Code natively supports list_resources / read_resource via MCP. Resources are registered dynamically — one @mcp.resource handler per namespace covering all namespace://slug URIs.
eswat2://manifest is a server-level resource listing all available URIs with descriptions — the LLM's entry point for discovery.
| Client | Interface | Transport |
|---|---|---|
| Claude Code | namespace:// resources | HTTP |
| Claude Desktop | list_uris / read_uri | HTTP |
| Browser / REST | /resolve?uri=… | HTTP |
Six @mcp.tool handlers for clients that don't support resources. All backed by the same kb.py loader.
namespace://slug URI and return contentkb-graph.html| Method | Path | Description |
|---|---|---|
| GET | /health | Liveness check |
| GET | /manifest | Server manifest — name, version, all namespaces |
| GET | /list_namespaces | All namespaces with entry counts |
| GET | /list_uris | All URIs with descriptions, optional ?namespace= filter |
| GET | /resolve?uri=<uri> | Resolve any namespace://slug URI and return content |
| GET | /graph | Full URI relationship graph (consumed by kb-graph.html) |
| — | /mcp | MCP protocol endpoint (FastMCP) — all MCP clients connect here |
| — | /docs | Auto-generated OpenAPI docs (FastAPI) |
claude mcp add eswat2 \
--transport http \
http://localhost:9100/mcp
{
"mcpServers": {
"eswat2": {
"type": "url",
"url": "http://localhost:9100/mcp"
}
}
}
modules/profile/ from _source reference material. Sources: podcast transcripts (biography, journeys), GitHub Pages (identity, projects, links), resume 2026 (career), spec + doc dirs (research).
identity.md · biography.md · journey-programming.md · journey-ui.md · resume.md · projects.md · research.md
pyproject.toml — package definition, dependencies, dev extras, pytest config.src/kb.py — KB loading logic: loads all kbs/*-kb.json at import time; exposes load_content(namespace, slug) → str and list_slugs(namespace) → list[str].src/server.py — stub only, no endpoints yet.modules/profile/ — seven placeholder markdown files.
@mcp.resource handler per namespace covering all namespace://slug URIs. eswat2://manifest registered as a server-level resource.@mcp.tool handlers provide equivalent access for clients that don't support resources. Both interfaces backed by the same kb.py loader. FastMCP server instructions describe the purpose so an LLM knows what it's connected to.
/health, /manifest, /list_namespaces, /list_uris, /resolve, /graph. FastMCP mounted at /mcp. FastAPI auto-docs at /docs.server.py and can be completed in a single session.
tests/test_content.py — unit tests for kb.py, no server needed.tests/test_resources.py — MCP resource tests via FastMCP Client.tests/test_tools.py — MCP tool tests (list_uris, read_uri, etc.) via FastMCP Client.tests/test_rest.py — REST endpoint tests via FastAPI TestClient.
start.sh / stop.sh — launch and kill the server by port.README.md — setup, run instructions, MCP registration for Claude Code + Claude Desktop, REST reference, module editing guide.CLAUDE.md updated with run/test commands, port, and endpoints.
localhost:9100) — full access, no auth. Vercel — all namespaces, X-API-Key required on every route. Simpler than a public/private slug split; avoids classifying every new entry.api/index.py is a separate server definition that imports the same kb.py but registers a narrower tool surface. No content duplication. MCP endpoint becomes https://<project>.vercel.app/mcp. Register as eswat2-public to distinguish from the local registration.server.py and can be completed in a single session — no need to split them.