context-hub-mcp

A local-first MCP server that turns a .context/ folder of markdown files into a searchable knowledge layer for AI coding agents.

• write domain knowledge in markdown, keep it in git
• index it locally for fast retrieval
• expose it as MCP tools for Claude Code, Copilot, and other MCP clients

The markdown is the source of truth. SQLite is a local runtime index only — don't commit it.

Quickstart

# 1. Scaffold the .context/ folder
npx context-hub-mcp init

# 2. Build the local index
npx context-hub-mcp reindex

# 3. Generate MCP client config
npx context-hub-mcp config --target claude-code --cwd /absolute/path/to/project

Paste the generated JSON into your MCP client config. The client will then invoke serve automatically — you don't need to run it manually.

.context/ Structure

.context/
├── schema.md               ← authoring conventions
├── domains/                ← business rules, workflows, state machines
├── integrations/           ← third-party APIs, auth, webhooks
└── pitfalls/               ← gotchas, lessons learned, failure modes

Writing Knowledge

Every document needs YAML frontmatter:

---
title: Payment Rules
domain: payments
tags: [payments, line-pay]
last_verified: 2026-03-28
confidence: high
---

# Payment Rules

## Key Files

- `src/payments/service.ts` - entrypoint

## Payment State Machine

```mermaid
stateDiagram-v2
  pending --> paid
```

Fields: title, domain, tags, last_verified, confidence (high / medium / low), related (optional list of related doc paths)

Use Key Files sections for source references and state machine headings so structured parsing picks them up.

The related field accepts paths relative to .context/:

related:
  - integrations/stripe-webhooks.md
  - pitfalls/payment-idempotency.md

Importing Docs with Claude Code

If you use Claude Code, the repo includes a /import_context command that lets you turn any URL, wiki, or spec into a properly formatted .context/ document:

/import_context https://stripe.com/docs/webhooks
/import_context the spec at ./docs/payment-rules.md

Claude will fetch the source, distill the relevant knowledge, pick the right subdirectory, and write the file with correct frontmatter. Run npx context-hub-mcp reindex afterward to update the index.

MCP Tools

Tool	Purpose
list_domains	Discover available knowledge areas
search_context	Full-text search across indexed documents
get_context	Read a specific document
get_context_structured	Read a document as structured data (keyFiles, stateMachines, pitfalls, sections, related)
get_pitfalls	List pitfalls, optionally filtered by domain
list_tags	List all unique tags with document counts; optional domain filter
get_stale_docs	List documents with old or missing last_verified, or confidence: low
get_related	Return documents related to a given path (bidirectional, depth 1 or 2)
annotate_context	Leave a note on outdated or missing docs
rate_context	Mark whether a document was helpful
list_annotations	Review accumulated annotations
reindex_context	Force a fresh index rebuild

search_context — filtering params

In addition to a query string, search_context accepts optional filters:

Param	Type	Description
tags	string[]	OR-match: return docs that have any of the listed tags
confidence	string	Minimum confidence level (low, medium, high)
verified_after	string	Only docs with last_verified on or after this date (YYYY-MM-DD)
verified_before	string	Only docs with last_verified on or before this date (YYYY-MM-DD)

get_stale_docs — params

Param	Type	Default	Description
domain	string	—	Limit to a specific domain
days_threshold	number	90	Docs not verified within this many days are considered stale
limit	number	—	Cap the number of results

get_related — params

Param	Type	Description
path	string	Path of the source document (relative to .context/)
depth	1 | 2	1 returns directly linked docs; 2 also follows their links

CLI

npx context-hub-mcp init       # scaffold .context/ workspace
npx context-hub-mcp add        # create a new context document with frontmatter
npx context-hub-mcp reindex    # rebuild the local SQLite index
npx context-hub-mcp doctor     # inspect workspace health
npx context-hub-mcp config     # generate MCP client config JSON
npx context-hub-mcp serve      # run the MCP server (usually invoked by the client)

Run any command with --help for available flags.

add — flags

npx context-hub-mcp add [--domain <name>] [--title <title>] [--tags <a,b>] \
  [--confidence high|medium|low] [--template domain|integration|pitfall] \
  [--no-edit]

Flag	Description
--domain	Domain subfolder to place the file in (e.g. payments)
--title	Document title (used for the filename and frontmatter)
--tags	Comma-separated list of tags
--confidence	Initial confidence level; defaults to medium
--template	Starter template: domain, integration, or pitfall
--no-edit	Skip opening the file in $EDITOR after creation

Client Setup

Claude Code

npx context-hub-mcp config --target claude-code --cwd /absolute/path/to/project

<details> <summary>Example output</summary>

{
  "mcpServers": {
    "context-hub": {
      "command": "npx",
      "args": ["-y", "context-hub-mcp@latest", "serve", "--cwd", "/absolute/path/to/project"]
    }
  }
}

</details>

GitHub Copilot

npx context-hub-mcp config --target copilot --cwd /absolute/path/to/project

<details> <summary>Example output</summary>

{
  "mcpServers": {
    "context-hub": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "context-hub-mcp@latest", "serve", "--cwd", "/absolute/path/to/project"]
    }
  }
}

</details>

See also: examples/claude-code.mcp.json, examples/copilot.mcp.json

Configuration

context-hub.config.json is optional. Defaults:

{
  "contextDir": ".context",
  "dbPath": ".context/context_hub.db",
  "watch": true,
  "reindexDebounceMs": 250,
  "includeGlobs": ["**/*.md"],
  "excludeGlobs": ["**/.git/**"]
}

CLI flags override config file values. Relative paths resolve from cwd.

Troubleshooting

Search returns no results — run npx context-hub-mcp reindex, then npx context-hub-mcp doctor. Common causes: missing .context/, malformed frontmatter, file outside indexed globs.

Documents fail to parse — check that all 5 frontmatter fields are present and valid.

Database files appear in git — ensure .context/.gitignore contains context_hub.db, context_hub.db-shm, context_hub.db-wal.

Client cannot connect — verify the client uses stdio MCP, the --cwd path is correct, and the project has been indexed at least once.

License

MIT