{"id":30812722,"url":"https://github.com/doobidoo/mcp-context-provider","last_synced_at":"2026-08-27T23:55:33.319Z","repository":{"id":377292309,"uuid":"1041954162","full_name":"doobidoo/MCP-Context-Provider","owner":"doobidoo","description":"A static MCP server that provides AI models with persistent tool context, preventing context loss between chats.","archived":false,"fork":false,"pushed_at":"2026-05-21T05:41:25.000Z","size":27328,"stargazers_count":30,"open_issues_count":0,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-08-20T19:18:32.492Z","etag":null,"topics":["anthropic","automation","configuration","desktop-extension","developer-tools","devops","dxt","llm","mcp-servers","memory","productivity","workflow"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/doobidoo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"claude":"CLAUDE.md","gemini":null,"cursor":null,"copilot":null,"dco":null,"cla":null,"disclosure":null}},"created_at":"2025-08-21T09:04:20.000Z","updated_at":"2026-08-20T09:50:48.000Z","dependencies_parsed_at":"2026-08-20T19:28:43.702Z","dependency_job_id":null,"html_url":"https://github.com/doobidoo/MCP-Context-Provider","commit_stats":null,"previous_names":["doobidoo/mcp-context-provider"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/doobidoo/MCP-Context-Provider","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doobidoo%2FMCP-Context-Provider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doobidoo%2FMCP-Context-Provider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doobidoo%2FMCP-Context-Provider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doobidoo%2FMCP-Context-Provider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/doobidoo","download_url":"https://codeload.github.com/doobidoo/MCP-Context-Provider/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doobidoo%2FMCP-Context-Provider/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36947771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-27T02:00:07.166Z","response_time":96,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","automation","configuration","desktop-extension","developer-tools","devops","dxt","llm","mcp-servers","memory","productivity","workflow"],"created_at":"2025-09-06T07:08:45.583Z","updated_at":"2026-08-27T23:55:33.313Z","avatar_url":"https://github.com/doobidoo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Context Provider\n\n\u003e **Status:** beta — feature-complete, API stabilizing. See [CHANGELOG.md](CHANGELOG.md) for the latest release.\n\n  https://github.com/user-attachments/assets/d9c6c325-00f1-44d9-a805-b1d6588c0acf\n  \n  *Persistent context and learned instincts for Claude Desktop and Claude Code — surviving across sessions.*\n\nA 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.\n\n## Architecture\n\nTwo core concepts:\n\n| Concept | Description | Size | Lifetime |\n|---------|-------------|------|----------|\n| **Context** | Static tool rules, syntax preferences, auto-corrections | 200–1000 tokens | Permanent, manually authored |\n| **Instinct** | Learned rule extracted from sessions, confidence-scored | 20–80 tokens | Human-approved, evolves over time |\n\nFour subsystems:\n\n- **Engine** — loads, matches, and merges contexts + instincts into injection payloads\n- **MCP Server** (`src/server/index.ts`) — stdio + HTTP transport, 10 MCP tools\n- **CLI** (`mcp-cp`) — approval registry for instinct lifecycle management\n- **Memory Bridge** — optional sync of instincts to mcp-memory-service\n\n## Quick Start\n\n```bash\ngit clone https://codeberg.org/doobidoo/MCP-Context-Provider.git\ncd MCP-Context-Provider\nnpm install\nnpm run build\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"context-provider\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-context-provider/dist/server/index.js\"],\n      \"env\": {\n        \"CONTEXTS_PATH\": \"/path/to/mcp-context-provider/contexts\",\n        \"INSTINCTS_PATH\": \"/path/to/mcp-context-provider/instincts\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code (global)\n\nAdd to `~/.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"context-provider\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-context-provider/dist/server/index.js\"],\n      \"env\": {\n        \"CONTEXTS_PATH\": \"/path/to/mcp-context-provider/contexts\",\n        \"INSTINCTS_PATH\": \"/path/to/mcp-context-provider/instincts\"\n      }\n    }\n  }\n}\n```\n\n\u003e **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.\n\n### Claude Code Plugin (Marketplace)\n\nInstall directly from the marketplace:\n\n```bash\n/plugin marketplace add codeberg/doobidoo/MCP-Context-Provider\n/plugin install context-provider\n```\n\nThis auto-configures the MCP server with correct paths — no manual `.mcp.json` editing needed.\n\n### `/instill` Skill (Claude Code)\n\nInstall the skill globally (stays current with `git pull`):\n\n```bash\nmkdir -p ~/.claude/skills/instill\nln -s /path/to/mcp-context-provider/.claude/skills/instill.md ~/.claude/skills/instill/SKILL.md\n```\n\nThen use `/instill` at the end of productive sessions to distill learned patterns into instinct candidates.\n\n### Auto-Trigger Hook (Optional)\n\nThe instill-trigger hook automatically detects mistakes during a session and nudges Claude to suggest `/instill` when a threshold is reached. It monitors:\n\n- **User corrections** (UserPromptSubmit) — \"no not that\", \"that's wrong\", \"still broken\", etc.\n- **Tool failures** (PostToolUse) — non-zero exit codes, tracebacks, permission errors\n\nInstall the hook:\n\n```bash\ncp hooks/instill-trigger.js ~/.claude/hooks/core/instill-trigger.js\n```\n\nRegister in `~/.claude/settings.json` under both `UserPromptSubmit` and `PostToolUse`:\n\n```json\n{\n  \"type\": \"command\",\n  \"command\": \"node --no-warnings \\\"~/.claude/hooks/core/instill-trigger.js\\\"\",\n  \"timeout\": 3\n}\n```\n\n**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.\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_tool_context` | Get complete context for a tool category |\n| `get_syntax_rules` | Get syntax-specific rules for a tool |\n| `list_available_contexts` | List all loaded contexts |\n| `apply_auto_corrections` | Apply correction patterns to text |\n| `build_injection` | Combined context + instinct injection payload |\n| `list_instincts` | List all instincts with confidence scores, plus the resolved store path |\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CONTEXTS_PATH` | packaged `contexts/` | Path to `*_context.json` files |\n| `INSTINCTS_PATH` | `~/.local/share/mcp-context-provider/instincts` | Path to `*.instincts.yaml` files — see [Store Location](#store-location) |\n| `MEMORY_BRIDGE_URL` | — | Memory service base URL (enables bridge) |\n| `MEMORY_BRIDGE_API_KEY` | — | API key for memory service |\n| `MCP_SERVER_PORT` | `3100` | HTTP server port (only with `--http`) |\n\n## Store Location\n\nThe instincts store never depends on the directory the MCP host happened to launch\nthe server from. It resolves in this order:\n\n1. `INSTINCTS_PATH` — explicit override, always wins\n2. `./instincts` — only when the working directory is an `mcp-context-provider`\n   checkout (the development case)\n3. `$XDG_DATA_HOME/mcp-context-provider/instincts` — when `XDG_DATA_HOME` is set\n4. `~/.local/share/mcp-context-provider/instincts` — the default\n\nContexts resolve the same way, except the fallback is the `contexts/` directory\nshipped with the package: contexts are authored and versioned with the code,\ninstincts are learned user data.\n\nTo see which store is active:\n\n```bash\nmcp-cp path                     # prints the resolved directory\nnode dist/server/index.js       # logs both paths to stderr at startup\n```\n\nThe resolved path is also part of the `list_instincts` response (`store.path`,\n`store.resolved_from`) and of the `/health` payload in HTTP mode.\n\nIf the resolved store sits inside a git working tree that is not this\nrepository's checkout, the server warns at startup — that is the signal it\npicked up a working directory by accident and that learned instincts are about\nto be committed somewhere they do not belong.\n\nMerging a store from elsewhere:\n\n```bash\nmcp-cp import /path/to/learned.instincts.yaml --dry-run   # preview\nmcp-cp import /path/to/learned.instincts.yaml             # merge\n```\n\nExisting ids are never overwritten — a merge only adds. Legacy file shapes\n(top-level array, or `instincts:` as a list) are normalized on read.\n\n## Context Files\n\nContexts are JSON files in `contexts/*_context.json`. Each file matches one or more tools via glob patterns and injects static rules.\n\n```json\n{\n  \"tool_category\": \"git\",\n  \"description\": \"Git workflow rules\",\n  \"auto_convert\": false,\n  \"metadata\": {\n    \"version\": \"1.0.0\",\n    \"applies_to_tools\": [\"git:*\", \"Bash\"],\n    \"priority\": \"high\"\n  },\n  \"syntax_rules\": { ... },\n  \"auto_corrections\": {\n    \"fix-1\": { \"pattern\": \"...\", \"replacement\": \"...\" }\n  }\n}\n```\n\nAdd a new context by dropping a `*_context.json` file in `contexts/` and restarting the server.\n\n## Instincts\n\nInstincts are YAML files named `*.instincts.yaml` in the resolved store (see\n[Store Location](#store-location)). They are distilled from sessions via\n`/instill` and require human approval.\n\n```yaml\nversion: \"1.0\"\n\ninstincts:\n  my-rule:\n    id: my-rule\n    rule: \"Compact, actionable rule (20–80 tokens).\"\n    domain: git\n    tags: [git, workflow]\n    trigger_patterns:\n      - \"git commit\"\n    confidence: 0.75\n    min_confidence: 0.5\n    approved_by: human\n    active: true\n    created_at: \"2026-03-10T00:00:00Z\"\n    outcome_log: []\n```\n\nManage instincts with the CLI:\n\n```bash\nmcp-cp list\nmcp-cp show \u003cid\u003e\nmcp-cp approve \u003cid\u003e\nmcp-cp reject \u003cid\u003e\nmcp-cp tune \u003cid\u003e --confidence 0.8\nmcp-cp outcome \u003cid\u003e + \"worked well\"\nmcp-cp path\nmcp-cp import \u003cfile\u003e [--into \u003cname\u003e] [--dry-run]\n```\n\n## Development\n\n```bash\nnpm run build     # Compile TypeScript\nnpm run dev       # Watch mode\nnpm run lint      # Type-check only\nnpm test          # Run tests (vitest)\nnpm start         # stdio transport\nnpm run start:http  # HTTP transport on port 3100\n```\n\n## FAQ\n\n### Can I use `/instill` in Claude Desktop?\n\nNo. `/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.\n\nHowever, you can achieve the same result in Claude Desktop:\n\n1. **MCP tools work in both** - The `list_instincts` and `build_injection` tools are available in Claude Desktop via the MCP server.\n2. **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.\n\nThe 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.\n\n### Do `learned.instincts.yaml` files contain sensitive data?\n\nPotentially yes. Instincts distilled from work sessions may contain internal hostnames, customer names, infrastructure details, or operational procedures.\n\nThis is why the default store is a user-level directory outside any repository\n(`~/.local/share/mcp-context-provider/instincts`) and why the server warns when\nthe resolved store sits inside an unrelated git working tree. If you do point\n`INSTINCTS_PATH` at a checkout, add `instincts/learned.instincts.yaml` to that\nrepository's `.gitignore` and **review its contents before pushing**.\n\n### What is the difference between Contexts and Instincts?\n\n| | Contexts | Instincts |\n|---|---|---|\n| **Format** | JSON (`*_context.json`) | YAML (`*.instincts.yaml`) |\n| **Source** | Manually authored | Distilled from sessions via `/instill` |\n| **Size** | 200-1000 tokens | 20-80 tokens |\n| **Matching** | Tool-pattern globs | Regex trigger patterns |\n| **Lifecycle** | Static, versioned | Confidence-scored, evolves over time |\n| **Approval** | None needed | Requires `approved_by: human` |\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoobidoo%2Fmcp-context-provider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoobidoo%2Fmcp-context-provider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoobidoo%2Fmcp-context-provider/lists"}