add-mcp-package

name add-mcp-package description Scaffold a new MCP workspace package under packages/. Covers directory structure, pyproject.toml, tools.py, server.py, tool registration, formatter, __init__.py, tests, root server wiring, and uv sync. Use when: add new MCP package, new workspace, new tool server, scaffold package, add module. Add a New MCP Workspace Package Step-by-step guide to adding a new ra-mcp-<name>-mcp package to the workspace. Prerequisites Decide on your package name. Convention: <name>-mcp directory, ra-mcp-<name>-mcp PyPI name, ra_mcp_<name>_mcp Python import. Example mapping for a package called viewer : Slot Value Directory packages/mcps/viewer-mcp/ PyPI name ra-mcp-viewer-mcp Python package ra_mcp_viewer_mcp FastMCP instance viewer_mcp Server namespace "viewer" Step 1 — Create directory structure packages/mcps/<name>-mcp/ ├── pyproject.toml ├── README.md ├── src/ra_mcp_<name>_mcp/ │ ├── __init__.py │ ├── py.typed # empty file, PEP 561 marker │ ├── tools.py # FastMCP server + instructions + tool registration │ ├── server.py # Standalone entry point for isolated dev/testing │ └── formatter.py # LLM output formatting (optional) └── tests/ └── test_tools.py Step 2 — pyproject.toml [project] name = "ra-mcp-<name>-mcp" version = "0.3.0" # match current workspace version description = "<one-line description>" readme = "README.md" requires-python = ">=3.13" dependencies = [ # Domain package (if one exists): # "ra-mcp-<name>", "ra-mcp-common" , "fastmcp==3.4.2" , ] license = "Apache-2.0" [tool.uv.sources] # ra-mcp-<name> = { workspace = true } # uncomment if domain pkg exists ra-mcp-common = { workspace = true } [build-system] requires = [ "hatchling" ] build-backend = "hatchling.build" [tool.hatch.build.targets.wheel] packages = [ "src/ra_mcp_<name>_mcp" ] If the package depends on an existing domain package (e.g. ra-mcp-browse ), add it to dependencies and [tool.uv.sources] . If this is a standalone MCP package (like guide-mcp ), just depend on ra-mcp-common + fastmcp . Step 3 — tools.py This file creates the FastMCP instance and registers all tools/resources. from fastmcp import FastMCP <name>_mcp = FastMCP( name= "ra-<name>-mcp" , instructions= """ <Detailed LLM-facing instructions> - What this module does - List of available tools - Usage examples - Important caveats """ , ) @<name>_mcp.tool() async def <tool_name>(param1: str ) -> str : """Tool description for LLM understanding.""" ... For larger packages, split tool registration into a separate <name>_tool.py with a register_<name>_tool(mcp) function and call it from tools.py . Dataset (LanceDB-backed) MCPs — use the spine, don't reinvent If this is a LanceDB dataset MCP, depend on ra-mcp-dataset-lib and use the shared spine ( ra_mcp_dataset_lib ) instead of hand-rolling per-package clones: get_lancedb(LANCEDB_URI) for the connection (thread-safe, process-cached) — not a local _db / _get_db() . require_keyword(keyword, "'Example'") for the empty-keyword guard. lancedb_fts_search(...) + the predicate builders ( equals / at_least / at_most / text_contains / combine ) for the query. format_results(result, label="<Label>", render_record=_format_<x>_record) for output — only the per-record _format_<x>_record renderer is per-dataset. build_fts_index / build_scalar_indexes in the ingest path (never against live published data). A handler then reduces to: if err := require_keyword(...): return err , build filters, lancedb_fts_search , format_results , except → mark_span_error . Step 4 — server.py Standalone entry point for running the package in isolation (dev/testing). The argparse --stdio / --port + transport branch is shared — use run_dev_server from ra_mcp_common.dev_server (OTel handles logging when enabled). Pick a default port not already taken by another package. """Standalone server for ra-<name>-mcp. python -m ra_mcp_<name>_mcp.server python -m ra_mcp_<name>_mcp.server --stdio """ from ra_mcp_common.dev_server import run_dev_server from .tools import <name>_mcp def main () -> None : run_dev_server(<name>_mcp, description= "<Name> MCP Server" , default_port=30XX) if __name__ == "__main__" : main() Step 5 — __init__.py """MCP tools for <description>.""" from .tools import <name>_mcp __all__ = [ "<name>_mcp" ] Step 6 — py.typed Create an empty file at src/ra_mcp_<name>_mcp/py.typed . Step 7 — tests/test_tools.py """Tests for ra-mcp-<name>-mcp tools.""" from ra_mcp_<name>_mcp.tools import <name>_mcp def test_ <name>_mcp_has_name() -> None : assert <name>_mcp.name == "ra-<name>-mcp" Step 8 — README.md # ra-mcp- < name > -mcp < One-line description > . ## MCP Tools - ** < tool_name > ** : What it does ## Standalone usage python -m ra_mcp_<name>_mcp.server # HTTP on port 3001 python -m ra_mcp_<name>_mcp.server --stdio # stdio transport ## Part of ra-mcp Imported by the root server via `FastMCP.add_provider()` . Step 9 — Wire into root 9a. Root pyproject.toml — add dependency and source # In [project] dependencies, add: "ra-mcp-<name>-mcp", # In [tool.uv.sources], add: ra-mcp-<name> -mcp = { workspace = true } # In [tool.ruff.lint.isort] known-first-party, add: "ra_mcp_<name>_mcp" 9b. src/ra_mcp_server/server.py — register the module Add import at the top alongside the other module imports: from ra_mcp_<name>_mcp.tools import <name>_mcp Add entry to AVAILABLE_MODULES : "<name>" : { "server" : <name>_mcp, "description" : "<Short description for --list-modules>" , "default" : True , # or False if opt-in }, Step 10 — Sync and verify # Install the new package into the workspace uv sync # Verify the module loads uv run ra serve --list-modules # Run package tests uv run pytest packages/mcps/<name>-mcp/tests/ -v # Test standalone uv run python -m ra_mcp_<name>_mcp.server --port 3001 # Test with MCP Inspector npx @modelcontextprotocol/inspector uv run python -m ra_mcp_<name>_mcp.server --stdio Checklist packages/mcps/<name>-mcp/ directory with all files pyproject.toml has correct name, deps, and hatch wheel config tools.py exports a <name>_mcp FastMCP instance with tools registered server.py provides standalone --stdio / --port entry point __init__.py exports <name>_mcp py.typed marker exists tests/test_tools.py has at least a smoke test Root pyproject.toml : dependency added, source added, isort updated server.py in root: import added, AVAILABLE_MODULES entry added uv sync succeeds uv run ra serve --list-modules shows the new module