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

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

GitHub Copilot

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

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

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