MCP Context Provider

Status: beta — feature-complete, API stabilizing. See CHANGELOG.md for the latest release.

video.mp4

Persistent context and learned instincts for Claude Desktop and Claude Code — surviving across sessions.

A TypeScript MCP server that gives Claude persistent Contexts (static tool rules) and Instincts (learned, confidence-scored rules distilled from sessions). No more re-establishing context in every new chat.

Architecture

Two core concepts:

Concept	Description	Size	Lifetime
Context	Static tool rules, syntax preferences, auto-corrections	200–1000 tokens	Permanent, manually authored
Instinct	Learned rule extracted from sessions, confidence-scored	20–80 tokens	Human-approved, evolves over time

Four subsystems:

• Engine — loads, matches, and merges contexts + instincts into injection payloads
• MCP Server (src/server/index.ts) — stdio + HTTP transport, 10 MCP tools
• CLI (mcp-cp) — approval registry for instinct lifecycle management
• Memory Bridge — optional sync of instincts to mcp-memory-service

Quick Start

git clone https://codeberg.org/doobidoo/MCP-Context-Provider.git
cd MCP-Context-Provider
npm install
npm run build

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "context-provider": {
      "command": "node",
      "args": ["/path/to/mcp-context-provider/dist/server/index.js"],
      "env": {
        "CONTEXTS_PATH": "/path/to/mcp-context-provider/contexts",
        "INSTINCTS_PATH": "/path/to/mcp-context-provider/instincts"
      }
    }
  }
}

Claude Code (global)

Add to ~/.mcp.json:

{
  "mcpServers": {
    "context-provider": {
      "command": "node",
      "args": ["/path/to/mcp-context-provider/dist/server/index.js"],
      "env": {
        "CONTEXTS_PATH": "/path/to/mcp-context-provider/contexts",
        "INSTINCTS_PATH": "/path/to/mcp-context-provider/instincts"
      }
    }
  }
}

Important: Use absolute paths for both args and env values. Claude Code does not support the cwd field in MCP server configs — relative paths will resolve from the wrong directory and the server will fail to connect.

Claude Code Plugin (Marketplace)

Install directly from the marketplace:

/plugin marketplace add codeberg/doobidoo/MCP-Context-Provider
/plugin install context-provider

This auto-configures the MCP server with correct paths — no manual .mcp.json editing needed.

/instill Skill (Claude Code)

Install the skill globally (stays current with git pull):

mkdir -p ~/.claude/skills/instill
ln -s /path/to/mcp-context-provider/.claude/skills/instill.md ~/.claude/skills/instill/SKILL.md

Then use /instill at the end of productive sessions to distill learned patterns into instinct candidates.

Auto-Trigger Hook (Optional)

The instill-trigger hook automatically detects mistakes during a session and nudges Claude to suggest /instill when a threshold is reached. It monitors:

• User corrections (UserPromptSubmit) — "no not that", "that's wrong", "still broken", etc.
• Tool failures (PostToolUse) — non-zero exit codes, tracebacks, permission errors

Install the hook:

cp hooks/instill-trigger.js ~/.claude/hooks/core/instill-trigger.js

Register in ~/.claude/settings.json under both UserPromptSubmit and PostToolUse:

{
  "type": "command",
  "command": "node --no-warnings \"~/.claude/hooks/core/instill-trigger.js\"",
  "timeout": 3
}

Scoring: Corrections weighted 1.5x, tool failures 0.5x. Combined threshold: 3.0. Max 1 nudge per session. All tunable via CONFIG object in the hook file.

MCP Tools

Tool	Description
get_tool_context	Get complete context for a tool category
get_syntax_rules	Get syntax-specific rules for a tool
list_available_contexts	List all loaded contexts
apply_auto_corrections	Apply correction patterns to text
build_injection	Combined context + instinct injection payload
list_instincts	List all instincts with confidence scores, plus the resolved store path

Environment Variables

Variable	Default	Description
CONTEXTS_PATH	packaged contexts/	Path to *_context.json files
INSTINCTS_PATH	~/.local/share/mcp-context-provider/instincts	Directory holding learned.instincts.yaml — see Store Location
MEMORY_BRIDGE_URL	—	Memory service base URL (enables bridge)
MEMORY_BRIDGE_API_KEY	—	API key for memory service
MCP_SERVER_PORT	3100	HTTP server port (only with --http)

Store Location

The instincts store never depends on the directory the MCP host happened to launch the server from. It resolves in this order:

1. INSTINCTS_PATH — explicit override, always wins
2. ./instincts — only when the working directory is an mcp-context-provider checkout (the development case)
3. $XDG_DATA_HOME/mcp-context-provider/instincts — when XDG_DATA_HOME is set
4. ~/.local/share/mcp-context-provider/instincts — the default

Contexts resolve the same way, except the fallback is the contexts/ directory shipped with the package: contexts are authored and versioned with the code, instincts are learned user data.

To see which store is active:

mcp-cp path                     # prints the resolved directory
node dist/server/index.js       # logs both paths to stderr at startup

The resolved path is also part of the list_instincts response (store.path, store.resolved_from) and of the /health payload in HTTP mode.

If the resolved store sits inside a git working tree that is not this repository's checkout, the server warns at startup — that is the signal it picked up a working directory by accident and that learned instincts are about to be committed somewhere they do not belong.

Merging a store from elsewhere:

mcp-cp import /path/to/learned.instincts.yaml --dry-run   # preview
mcp-cp import /path/to/learned.instincts.yaml             # merge

The merge always targets the canonical learned.instincts.yaml.

Existing ids are never overwritten — a merge only adds. Legacy file shapes (top-level array, or instincts: as a list) are normalized on read.

Context Files

Contexts are JSON files in contexts/*_context.json. Each file matches one or more tools via glob patterns and injects static rules.

{
  "tool_category": "git",
  "description": "Git workflow rules",
  "auto_convert": false,
  "metadata": {
    "version": "1.0.0",
    "applies_to_tools": ["git:*", "Bash"],
    "priority": "high"
  },
  "syntax_rules": { ... },
  "auto_corrections": {
    "fix-1": { "pattern": "...", "replacement": "..." }
  }
}

Add a new context by dropping a *_context.json file in contexts/ and restarting the server.

Instincts

Instincts live in exactly one file, learned.instincts.yaml, inside the resolved store (see Store Location). They are distilled from sessions via /instill and require human approval.

Any other *.instincts.yaml in that directory is not read. It is reported by name at startup and by mcp-cp list, together with the mcp-cp import command that merges it — so a second file can never drift into the store unnoticed, and no instinct is ever loaded from a file you did not intend.

version: "1.0"

instincts:
  my-rule:
    id: my-rule
    rule: "Compact, actionable rule (20–80 tokens)."
    domain: git
    tags: [git, workflow]
    trigger_patterns:
      - "git commit"
    confidence: 0.75
    min_confidence: 0.5
    approved_by: human
    active: true
    created_at: "2026-03-10T00:00:00Z"
    outcome_log: []

Manage instincts with the CLI:

mcp-cp list
mcp-cp show <id>
mcp-cp approve <id>
mcp-cp reject <id>
mcp-cp tune <id> --confidence 0.8
mcp-cp outcome <id> + "worked well"
mcp-cp path
mcp-cp import <file> [--dry-run]

Development

npm run build     # Compile TypeScript
npm run dev       # Watch mode
npm run lint      # Type-check only
npm test          # Run tests (vitest)
npm start         # stdio transport
npm run start:http  # HTTP transport on port 3100

FAQ

Can I use /instill in Claude Desktop?

No. /instill is a Claude Code skill (.claude/skills/instill.md) and only works in the Claude Code CLI. Claude Desktop does not have a skill system.

However, you can achieve the same result in Claude Desktop:

1. MCP tools work in both - The list_instincts and build_injection tools are available in Claude Desktop via the MCP server.
2. For the instill workflow, create a Claude Desktop Project and paste the instill instructions as Custom Instructions. Claude Desktop can then use desktop-commander or similar MCP servers to write YAML files.

The reason /instill is not exposed as an MCP tool: it is an interactive, multi-step workflow (analyze conversation, present candidates, await user decision, write YAML). MCP tools return a single response and cannot drive multi-turn interactions.

Do learned.instincts.yaml files contain sensitive data?

Potentially yes. Instincts distilled from work sessions may contain internal hostnames, customer names, infrastructure details, or operational procedures.

This is why the default store is a user-level directory outside any repository (~/.local/share/mcp-context-provider/instincts) and why the server warns when the resolved store sits inside an unrelated git working tree. If you do point INSTINCTS_PATH at a checkout, add instincts/learned.instincts.yaml to that repository's .gitignore and review its contents before pushing.

What is the difference between Contexts and Instincts?

	Contexts	Instincts
Format	JSON (*_context.json)	YAML (*.instincts.yaml)
Source	Manually authored	Distilled from sessions via /instill
Size	200-1000 tokens	20-80 tokens
Matching	Tool-pattern globs	Regex trigger patterns
Lifecycle	Static, versioned	Confidence-scored, evolves over time
Approval	None needed	Requires approved_by: human

Changelog

See CHANGELOG.md.

License

Apache-2.0 — see LICENSE.