MCP Context Provider

https://github.com/user-attachments/assets/d9c6c325-00f1-44d9-a805-b1d6588c0acf

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, 6 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://github.com/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 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

Environment Variables

Variable	Default	Description
CONTEXTS_PATH	./contexts	Path to *_context.json files
INSTINCTS_PATH	./instincts	Path to *.instincts.yaml files
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)

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 are YAML files in instincts/*.instincts.yaml. They are distilled from sessions via /instill and require human approval.

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"

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. The learned.instincts.yaml file is tracked by git by default, so review its contents before pushing to public repositories. Consider adding it to .gitignore if your instincts contain proprietary information.

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

MIT