skill-mcp

Serve company documentation through one read-only MCP server. Point the server at any compatible Markdown folder and agents get two portable tools: search(query) to discover relevant information and fetch(id) to retrieve an authoritative document with its canonical URL and metadata.

The content model is deliberately broader than Agent Skills. It works for internal-library guidance, data-source instructions, engineering standards, runbooks, architecture notes, and any other bounded company context.

Run the example catalog

Requires Python 3.14 or newer and uv.

git clone https://github.com/jacobragsdale/skill-mcp.git
cd skill-mcp
uv sync --locked
SKILL_MCP_CONTENT_ROOT=/absolute/path/to/skill-mcp/examples/context uv run skill-mcp

Connect an MCP client to http://127.0.0.1:8000/mcp. The readiness endpoint validates the live catalog and reports its document count:

curl http://127.0.0.1:8000/health

FastAPI's OpenAPI UI is available at http://127.0.0.1:8000/docs.

To keep the path in a local file, copy .env.example, set its required value, and load it explicitly:

cp .env.example .env
uv run --env-file .env skill-mcp

The root is selected once at startup. Restart with a different SKILL_MCP_CONTENT_ROOT to serve another compatible folder. Documents inside the selected folder are validated and reread on every tool call, so edits go live without rebuilding or restarting the server.

Add information to search and fetch

Create a UTF-8 Markdown file anywhere below the configured content root. Keep one file focused on one fetchable topic and begin it with this strict YAML frontmatter:

---
id: data/customer-orders
title: Customer order data source
url: https://docs.example.com/data/customer-orders
summary: Find governed customer order data and choose the supported table.
metadata:
  owner: Data Platform
  authority: example
  updated: "2026-08-04"
---

# Customer order data

The supported source is ...

Then validate the entire root:

uv run skill-mcp-validate /absolute/path/to/company-context

Repository contributors can invoke the repo-scoped $add-company-context skill for the complete authoring and retrieval-regression workflow. Do not hardcode topic-specific branches in search or fetch; adding a valid document makes it available to both tools automatically.

Content contract

The configured root is scanned recursively for non-hidden *.md files. Every discovered file must satisfy the contract; one invalid document fails the catalog rather than silently serving partial company guidance.

Field	Requirement
id	Required stable lowercase identifier using path segments and hyphens, such as engineering/python-settings. It must be unique across the root.
title	Required human-readable title, 1–200 characters.
url	Required absolute HTTP or HTTPS canonical source URL.
summary	Required search-oriented summary, 1–500 characters.
metadata	Optional string-to-string provenance fields such as owner, authority, version, and updated. Quote YAML values that would otherwise become dates or numbers.
body	Required non-empty Markdown. A document may contain at most 60,000 characters so a fetch stays bounded.

Keep identifiers stable when moving files: callers fetch by frontmatter id, not by filesystem path. Hidden directories, hidden files, and common cache directories are ignored. Symlinks that escape the configured root, duplicate identifiers, malformed YAML, unknown frontmatter fields, non-UTF-8 text, and empty bodies are rejected.

MCP reference

The server intentionally exposes tools only. That is the common denominator across coding agents; clients do not need MCP resource or prompt support.

Tool	Input	Structured result
search	query: string (1–500 characters)	{results: [{id, title, url}]} with at most 10 BM25-ranked matches.
fetch	id: string from search	{id, title, text, url, metadata} for one exact document.

Both tools are declared read-only, non-destructive, idempotent, and closed-world. Search is deterministic keyword retrieval over identifiers, titles, summaries, metadata, and Markdown bodies. Titles and summaries receive extra weight; an exact phrase in either receives a further boost. A query with no matching terms returns an empty results array.

The server instructions tell agents to search whenever company-specific context could help, fetch before relying on a result, preserve canonical URLs as provenance, and avoid inventing internal facts when the catalog has no answer.

Production boundary

The included process binds only to 127.0.0.1:8000 and has no built-in authentication or browser CORS policy. For company deployment, put it behind your existing identity-aware gateway or reverse proxy, terminate TLS there, and record per-tool latency, result count, fetched document id, caller, and errors there or in structured application logs. Do not log full queries or document bodies unless your privacy policy explicitly permits it.

Authentication controls who can reach a server; it is not document-level authorization. Run separate catalogs or add an authorization-aware storage adapter before mixing content with different audiences. The server is read-only and never executes, edits, or installs any served content.

Develop

uv sync --locked
uv run pytest
uv run pre-commit run --all-files
uv build --no-sources

Retrieval examples live in examples/context/, and human-readable evaluation queries live in evals/retrieval.json. The test suite checks every evaluation, strict content rejection, live root swapping, the official in-memory MCP client contract, tool annotations and schemas, and the FastAPI lifespan and health route. CI runs the suite and all repository checks on Python 3.14.