mcp_for_agents

A small Python library for building local, offline MCP servers that expose the documentation of your favorite open-source packages to AI agents (opencode, Claude Code, etc.). Zero network dependency at query time.

What it is

A reusable build_server() factory plus a thin per-package template. Each package's MCP server becomes a 3-line Python file:

from mcp_for_agents import build_server

if __name__ == "__main__":
    build_server().run()

The library handles indexing the docs mirror, scoring search queries, and exposing the three tools (list_doc_sources, search_docs, get_doc) over stdio.

Related MCP server: docs-cache-mcp

Repository layout

Reference implementation

../MLOps_Tutorials/other_notes/Automations/opencode/mcp-servers/langgraph-docs/ is a working example of a per-package MCP server built using this library (the library was extracted from that standalone script). It mirrors what a copy of template/ looks like after per-package customization.

Quick start

To use the library in a per-package MCP server:

mkdir -p ~/.config/opencode/mcp-servers/<name>-docs
cp -R <PATH_TO_THIS_REPO>/template/ ~/.config/opencode/mcp-servers/<name>-docs/
cd ~/.config/opencode/mcp-servers/<name>-docs

uv init --no-readme
uv add /path/to/mcp_for_agents

The library gets installed as a regular dependency. server.py runs as a thin entry point. To work on the library itself, see Development below.

Development

cd /path/to/mcp_for_agents

# Install the library in editable mode with dev deps
uv sync --dev

# Run tests
uv run pytest

# Lint and format
uv run ruff check .
uv run ruff format .

To verify a package's mirror after setting it up:

uv run mcp-for-agents-test ~/docs-mirror/<name>

(Install the CLI globally with uv tool install /path/to/mcp_for_agents if you want it on PATH.)

Releasing

Releases are cut with scripts/release.sh, which keeps the three version sources (pyproject.toml, src/mcp_for_agents/__init__.py, and the git tag) in sync. The script never pushes; pushing stays manual so nothing leaves the machine unreviewed.

Prerequisites: clean tree, on main, uv on PATH.

./scripts/release.sh patch   # or: minor, major

What the script does, in order:

1. Aborts unless the tree is clean and you are on main.

2. Reads the current version from both pyproject.toml and __init__.py, and aborts if they disagree (version drift must be fixed by hand first).

3. Computes the next version (semver; major/minor reset the lower segments to zero) and aborts if the tag already exists. This check runs before anything is modified, so a duplicate tag cannot leave a half-done commit behind.

4. Writes the new version to both files and stubs a CHANGELOG.md entry above the newest existing one.

5. Runs ruff check, ruff format --check, and pytest (all --frozen, so the lockfile cannot shift). Any failure aborts before the commit.

6. Commits the three files as [chore] release vX.Y.Z and creates annotated tag vX.Y.Z.

After it finishes:

git show HEAD && git show vX.Y.Z   # review
# fill in the TODO stubs in CHANGELOG.md, then:
git add CHANGELOG.md && git commit -m "[docs] describe vX.Y.Z changes"
git push origin main --follow-tags  # ship

Adding a new package

See playbook.md for the three-phase process: review the upstream repo, sparse-clone the docs mirror, and wire the MCP server using the template.

Requirements

• uv 0.4+ on PATH

• git

• Python 3.14+ (uv will fetch one if missing)