{"_id":"@crack-break-make/mcp-grimoire","_rev":"13-68753180555d0584946560edb7f2936a","name":"@crack-break-make/mcp-grimoire","dist-tags":{"rc":"1.0.0-rc.0","next":"1.0.0-rc.1","latest":"1.0.1"},"versions":{"1.0.0-rc.0":{"name":"@crack-break-make/mcp-grimoire","version":"1.0.0-rc.0","keywords":["mcp","model-context-protocol","ai","tools","grimoire","spellbook","orchestrator","lazy-loading"],"author":{"name":"Mohan Sharma"},"license":"ISC","_id":"@crack-break-make/mcp-grimoire@1.0.0-rc.0","maintainers":[{"name":"crack-break-make","email":"crack.break.make@gmail.com"}],"homepage":"https://github.com/crack-break-make/mcp-grimoire#readme","bugs":{"url":"https://github.com/crack-break-make/mcp-grimoire/issues"},"bin":{"grimoire":"dist/cli.js","mcp-grimoire":"dist/index.js"},"dist":{"shasum":"207e98bd7934df75a5fb701a0a10f4cdcdeb74f0","tarball":"https://registry.npmjs.org/@crack-break-make/mcp-grimoire/-/mcp-grimoire-1.0.0-rc.0.tgz","fileCount":108,"integrity":"sha512-5xFQmZ6kLUm+7CVOIcpIk3kU8ECRtMnYkpvWj57Jg86CrNl5p8s0s1VEBQZzgH4aPxQtVGbLZPbVQiuODvbCkw==","signatures":[{"sig":"MEUCIQDgRA5ww1aIOAgX7eCyhwjJ3sWNoOp3U9Wz6ZcvPvhaDgIgCNf2nddVAFAU0bFUZkgjLRl9hAqJXYRVWFJGNpaqC/A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":442585},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=22.0.0"},"gitHead":"3d1eb6aefd6f84675728fb666f32ee6b3d8665f3","scripts":{"dev":"tsx watch src/index.ts","lint":"eslint \"src/**/*.ts\"","test":"vitest run","build":"tsc","clean":"rm -rf dist coverage html","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"docs/**/*.md\" \"*.md\"","prepare":"husky","test:ui":"vitest --ui","lint:fix":"eslint \"src/**/*.ts\" --fix","clean:all":"rm -rf dist coverage node_modules pnpm-lock.yaml","test:watch":"vitest","type-check":"tsc --noEmit","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"docs/**/*.md\" \"*.md\"","test:coverage":"vitest run --coverage","prepublishOnly":"pnpm run clean && pnpm run type-check && pnpm run lint && pnpm run test && pnpm run build","test:containers":"vitest run --config vitest.container.config.ts","test:containers:watch":"vitest --config vitest.container.config.ts"},"_npmUser":{"name":"crack-break-make","email":"crack.break.make@gmail.com"},"repository":{"url":"git+https://github.com/crack-break-make/mcp-grimoire.git","type":"git"},"_npmVersion":"11.6.2","description":"Your spellbook for MCP servers - intelligent orchestration with lazy loading and expert incantations","directories":{},"lint-staged":{"*.ts":["secretlint","prettier --write"],"*.{js,json,yaml,yml,md}":["secretlint","prettier --write"],"src/**/!(*.test|*.spec).ts":["eslint --fix --max-warnings 0"]},"_nodeVersion":"25.2.1","dependencies":{"yaml":"^2.8.2","chokidar":"^5.0.0","msgpackr":"^1.11.8","commander":"^12.0.0","env-paths":"^3.0.0","@xenova/transformers":"^2.17.2","@modelcontextprotocol/sdk":"^1.25.2"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","husky":"^9.1.7","eslint":"^9.39.2","vitest":"^4.0.16","prettier":"^3.7.4","@vitest/ui":"^4.0.16","secretlint":"^11.2.5","typescript":"^5.9.3","@types/node":"^25.0.5","lint-staged":"^16.2.7","@types/express":"^5.0.6","testcontainers":"^11.11.0","@vitest/coverage-v8":"^4.0.16","eslint-config-prettier":"^10.1.8","@typescript-eslint/parser":"^8.52.0","@secretlint/secretlint-rule-aws":"^11.2.5","@secretlint/secretlint-rule-gcp":"^11.2.5","@typescript-eslint/eslint-plugin":"^8.52.0","@secretlint/secretlint-rule-preset-recommend":"^11.2.5"},"_npmOperationalInternal":{"tmp":"tmp/mcp-grimoire_1.0.0-rc.0_1768653700543_0.6688872384938971","host":"s3://npm-registry-packages-npm-production"}},"1.0.0-rc.1":{"name":"@crack-break-make/mcp-grimoire","version":"1.0.0-rc.1","keywords":["mcp","model-context-protocol","ai","tools","grimoire","spellbook","orchestrator","lazy-loading"],"author":{"name":"Mohan Sharma"},"license":"ISC","_id":"@crack-break-make/mcp-grimoire@1.0.0-rc.1","maintainers":[{"name":"crack-break-make","email":"crack.break.make@gmail.com"}],"homepage":"https://github.com/crack-break-make/mcp-grimoire#readme","bugs":{"url":"https://github.com/crack-break-make/mcp-grimoire/issues"},"bin":{"grimoire":"dist/cli.js","mcp-grimoire":"dist/index.js"},"dist":{"shasum":"d0b62fbfe4972a04a1062997c13881a76fa37653","tarball":"https://registry.npmjs.org/@crack-break-make/mcp-grimoire/-/mcp-grimoire-1.0.0-rc.1.tgz","fileCount":132,"integrity":"sha512-WXSDoLZhsaZkv/ZUt8HDqCvyv1tZLwkLFX8rZMbXzTLI4ovDOChA1EloQG8TBUfCSUL0jwsC214RpFqNRJpEGg==","signatures":[{"sig":"MEYCIQC2gIgChXD5fIuiXF1HpaKysfGCD1NPb7dEkqtl2GbTaAIhAKXIFpzcRxGnNDTd2S7gQIeR4ohPLBVApreBWiIKHqBp","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":649364},"main":"dist/index.js","_from":"file:crack-break-make-mcp-grimoire-1.0.0-rc.1.tgz","types":"dist/index.d.ts","engines":{"node":">=22.0.0"},"scripts":{"dev":"tsx watch src/index.ts","lint":"eslint \"src/**/*.ts\"","test":"vitest run","build":"tsc","clean":"rm -rf dist coverage html","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"docs/**/*.md\" \"*.md\"","test:ui":"vitest --ui","lint:fix":"eslint \"src/**/*.ts\" --fix","clean:all":"rm -rf dist coverage node_modules pnpm-lock.yaml","test:unit":"vitest run --project unit","test:watch":"vitest","type-check":"tsc --noEmit","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"docs/**/*.md\" \"*.md\"","test:coverage":"vitest run --coverage","test:containers":"vitest run --config vitest.container.config.ts","test:unit:watch":"vitest --project unit","test:integration":"vitest run --project integration","test:coverage:unit":"vitest run --project unit --coverage","test:containers:watch":"vitest --config vitest.container.config.ts","test:integration:watch":"vitest --project integration"},"_npmUser":{"name":"crack-break-make","email":"crack.break.make@gmail.com"},"_resolved":"/private/var/folders/xp/jvzwqjlx5m590rgnc305p4zc0000gn/T/a569f54609b4465097119f914568593e/crack-break-make-mcp-grimoire-1.0.0-rc.1.tgz","_integrity":"sha512-WXSDoLZhsaZkv/ZUt8HDqCvyv1tZLwkLFX8rZMbXzTLI4ovDOChA1EloQG8TBUfCSUL0jwsC214RpFqNRJpEGg==","repository":{"url":"git+https://github.com/crack-break-make/mcp-grimoire.git","type":"git"},"_npmVersion":"11.7.0","description":"Your spellbook for MCP servers - intelligent orchestration with lazy loading and expert incantations","directories":{},"lint-staged":{"*.ts":["secretlint","prettier --write"],"*.{js,json,yaml,yml,md}":["secretlint","prettier --write"],"src/**/!(*.test|*.spec).ts":["eslint --fix --max-warnings 0"]},"_nodeVersion":"25.4.0","dependencies":{"yaml":"^2.8.2","chokidar":"^5.0.0","msgpackr":"^1.11.8","commander":"^12.0.0","env-paths":"^3.0.0","@xenova/transformers":"^2.17.2","@modelcontextprotocol/sdk":"^1.25.2"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"tsx":"^4.21.0","husky":"^9.1.7","eslint":"^9.39.2","vitest":"^4.0.16","prettier":"^3.7.4","@vitest/ui":"^4.0.16","secretlint":"^11.2.5","typescript":"^5.9.3","@types/node":"^25.0.5","lint-staged":"^16.2.7","@types/express":"^5.0.6","testcontainers":"^11.11.0","@vitest/coverage-v8":"^4.0.16","eslint-config-prettier":"^10.1.8","@typescript-eslint/parser":"^8.52.0","@secretlint/secretlint-rule-aws":"^11.2.5","@secretlint/secretlint-rule-gcp":"^11.2.5","@typescript-eslint/eslint-plugin":"^8.52.0","@secretlint/secretlint-rule-preset-recommend":"^11.2.5"},"_npmOperationalInternal":{"tmp":"tmp/mcp-grimoire_1.0.0-rc.1_1769245520130_0.25114481513516096","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@crack-break-make/mcp-grimoire","version":"1.0.1","description":"Your spellbook for MCP servers - intelligent orchestration with lazy loading and expert incantations","main":"dist/index.js","bin":{"grimoire":"dist/cli.js","mcp-grimoire":"dist/index.js"},"types":"dist/index.d.ts","repository":{"type":"git","url":"git+https://github.com/crack-break-make/mcp-grimoire.git"},"bugs":{"url":"https://github.com/crack-break-make/mcp-grimoire/issues"},"homepage":"https://github.com/crack-break-make/mcp-grimoire#readme","engines":{"node":">=22.0.0"},"lint-staged":{"*.ts":["secretlint","prettier --write"],"src/**/!(*.test|*.spec).ts":["eslint --fix --max-warnings 0"],"*.{js,json,yaml,yml,md}":["secretlint","prettier --write"]},"keywords":["mcp","model-context-protocol","ai","tools","grimoire","spellbook","orchestrator","lazy-loading"],"author":{"name":"Mohan Sharma"},"license":"ISC","dependencies":{"@modelcontextprotocol/sdk":"^1.25.2","@xenova/transformers":"^2.17.2","chokidar":"^5.0.0","commander":"^12.0.0","env-paths":"^3.0.0","msgpackr":"^1.11.8","yaml":"^2.8.2"},"devDependencies":{"@secretlint/secretlint-rule-aws":"^11.2.5","@secretlint/secretlint-rule-gcp":"^11.2.5","@secretlint/secretlint-rule-preset-recommend":"^11.2.5","@types/express":"^5.0.6","@types/node":"^25.0.5","@typescript-eslint/eslint-plugin":"^8.52.0","@typescript-eslint/parser":"^8.52.0","@vitest/coverage-v8":"^4.0.16","@vitest/ui":"^4.0.16","eslint":"^9.39.2","eslint-config-prettier":"^10.1.8","husky":"^9.1.7","lint-staged":"^16.2.7","prettier":"^3.7.4","secretlint":"^11.2.5","testcontainers":"^11.11.0","tsx":"^4.21.0","typescript":"^5.9.3","vitest":"^4.0.16"},"scripts":{"dev":"tsx watch src/index.ts","build":"tsc","type-check":"tsc --noEmit","lint":"eslint \"src/**/*.ts\"","lint:fix":"eslint \"src/**/*.ts\" --fix","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"docs/**/*.md\" \"*.md\"","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"docs/**/*.md\" \"*.md\"","test":"vitest run","test:unit":"vitest run --project unit","test:integration":"vitest run --project integration","test:watch":"vitest","test:unit:watch":"vitest --project unit","test:integration:watch":"vitest --project integration","test:coverage":"vitest run --coverage","test:coverage:unit":"vitest run --project unit --coverage","test:ui":"vitest --ui","test:containers":"vitest run --config vitest.container.config.ts","test:containers:watch":"vitest --config vitest.container.config.ts","clean":"rm -rf dist coverage html","clean:all":"rm -rf dist coverage node_modules pnpm-lock.yaml"},"_id":"@crack-break-make/mcp-grimoire@1.0.1","_integrity":"sha512-L3cN8umj6TP+ERKOleRERIHDf4/cjfyQxNJp8rH14PJn1iv+srvnHfk5KABwFKcbuX6BxbCLn3D9VGUxm5QiLw==","_resolved":"/private/var/folders/xp/jvzwqjlx5m590rgnc305p4zc0000gn/T/3454c323b4e581919a60ec041ee71e26/crack-break-make-mcp-grimoire-1.0.1.tgz","_from":"file:crack-break-make-mcp-grimoire-1.0.1.tgz","_nodeVersion":"25.4.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-L3cN8umj6TP+ERKOleRERIHDf4/cjfyQxNJp8rH14PJn1iv+srvnHfk5KABwFKcbuX6BxbCLn3D9VGUxm5QiLw==","shasum":"80f1a274a4d1da117023a09518b237f696b81db4","tarball":"https://registry.npmjs.org/@crack-break-make/mcp-grimoire/-/mcp-grimoire-1.0.1.tgz","fileCount":135,"unpackedSize":653559,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIClnV8YtVlsVugscBwcjmCLZHVplmoe0nYPJMBncClsEAiEA6bCOfzEM614J93gtnSEUZoLt9zm/ZemXYnfFCTH3RAk="}]},"_npmUser":{"name":"crack-break-make","email":"crack.break.make@gmail.com"},"directories":{},"maintainers":[{"name":"crack-break-make","email":"crack.break.make@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-grimoire_1.0.1_1769260870649_0.7580332860193988"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-17T12:41:40.323Z","modified":"2026-01-24T13:21:10.946Z","1.0.0":"2026-01-16T09:07:25.665Z","1.0.0-beta.0":"2026-01-16T15:11:50.990Z","1.0.0-beta.1":"2026-01-16T15:41:06.956Z","1.0.0-beta.2":"2026-01-17T07:08:27.675Z","1.0.0-beta.3":"2026-01-17T09:09:05.458Z","1.0.0-beta.4":"2026-01-17T10:01:51.839Z","1.0.0-rc.0":"2026-01-17T12:41:40.696Z","1.0.0-rc.1":"2026-01-24T09:05:20.327Z","1.0.1":"2026-01-24T13:21:10.841Z"},"bugs":{"url":"https://github.com/crack-break-make/mcp-grimoire/issues"},"author":{"name":"Mohan Sharma"},"license":"ISC","homepage":"https://github.com/crack-break-make/mcp-grimoire#readme","keywords":["mcp","model-context-protocol","ai","tools","grimoire","spellbook","orchestrator","lazy-loading"],"repository":{"type":"git","url":"git+https://github.com/crack-break-make/mcp-grimoire.git"},"description":"Your spellbook for MCP servers - intelligent orchestration with lazy loading and expert incantations","maintainers":[{"name":"crack-break-make","email":"crack.break.make@gmail.com"}],"readme":"
\n \"MCP\n
\n\n**Your intelligent spellbook for MCP servers** - Lazy loading orchestration with 97% token savings\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](.)\n[![License](https://img.shields.io/badge/license-ISC-blue)](.)\n[![npm version](https://img.shields.io/npm/v/@crack-break-make/mcp-grimoire)](https://www.npmjs.com/package/@crack-break-make/mcp-grimoire)\n\n---\n\n## ๐Ÿ“บ Video Tutorial\n\n**New to MCP Grimoire?** Watch this comprehensive walkthrough:\n\n[![MCP Grimoire Tutorial](https://img.youtube.com/vi/1N0RN4f5EuA/maxresdefault.jpg)](https://youtu.be/1N0RN4f5EuA)\n\n๐ŸŽฅ [**Watch on YouTube: MCP Grimoire - Complete Setup & Usage Guide**](https://youtu.be/1N0RN4f5EuA)\n\n---\n\n## ๐ŸŽฏ What is MCP Grimoire?\n\n**MCP Grimoire** is an intelligent orchestrator for [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers. It acts as a smart gateway between AI agents (like Claude Desktop, GitHub Copilot) and your MCP tools, solving critical performance and usability problems in AI-powered development workflows.\n\n### The Problem\n\nTraditional MCP implementations suffer from three critical issues:\n\n**1. Context Overload (Token Waste) ๐Ÿ’ธ**\n\n- Loading 50+ tools at startup consumes 40,000+ tokens\n- Degrades AI performance and increases API costs\n- Results in slower responses and confused tool selection\n\n**2. Missing Domain Expertise ๐Ÿคท**\n\n- MCP tools lack contextual guidance and best practices\n- Users must manually prompt for security patterns\n- Leads to vulnerabilities and inconsistent usage\n\n**3. Plugin Development Complexity ๐Ÿ”ง**\n\n- No standardized patterns for creating MCP plugins\n- Difficult to maintain and extend\n- Fragmented ecosystem\n\n### The Solution\n\nMCP Grimoire achieves **97% token reduction** through:\n\nโœ… **Lazy Loading** - Spawns MCP servers only when needed, not all at startup
\nโœ… **Intent-Driven Discovery** - Matches queries to tools via hybrid keyword + semantic search
\nโœ… **Aggressive Cleanup** - Kills inactive servers after 5 turns of inactivity
\nโœ… **Steering Injection** - Embeds best practices directly into tool descriptions
\nโœ… **Transparent Operation** - Claude doesn't know about the complexity\n\n**Result**: From 40,000 tokens โ†’ 1,166 tokens average (~$0.20 โ†’ ~$0.006 per query)\n\n---\n\n## ๐Ÿš€ Quick Start\n\n### Prerequisites\n\n- **Node.js** 22+ (for running MCP servers)\n- **Claude Desktop** or **GitHub Copilot** (Any AI agent with MCP support)\n- Basic understanding of command-line tools\n\n### Setup Workflow\n\n```\n1. Create Spells (Terminal) โ†’ 2. Configure Grimoire (mcp.json) โ†’ 3. Use in AI Agent\n npx mcp-grimoire create Add to Claude/Copilot config Ask questions naturally\n - Interactive wizard - Grimoire runs as MCP gateway - Servers spawn on-demand\n - Auto-probes server - Debug with GRIMOIRE_DEBUG - Auto-cleanup after 5 turns idle\n```\n\n### 1. Create Spells First (in Terminal)\n\n**โš ๏ธ IMPORTANT**: Always create your spells BEFORE configuring the MCP server!\n\nRun the interactive wizard (recommended for all users):\n\n```bash\nnpx @crack-break-make/mcp-grimoire@latest create\n```\n\nThe wizard will:\n\n- โœ… Guide you through each configuration step\n- โœ… Automatically probe the server (validates connection)\n- โœ… Auto-generate keywords from discovered tools\n- โœ… Create intelligent steering instructions\n- โœ… **Prevent spell creation if server can't be reached**\n- โœ… Save spell to `(user.home)/.grimoire/yourspell.spell.yaml`\n\n**Why probe matters**: If probing fails, the spell is NOT created (prevents broken configs).\n\n**List your spells**: `npx @crack-break-make/mcp-grimoire@latest list`\n\n### 2. Configure MCP Server (in Claude Desktop / GitHub Copilot)\n\n**Only after creating spells**, add Grimoire to your MCP configuration.\n\n๐Ÿ“š **Learn more about MCP configuration**:\n\n- [VS Code Copilot MCP Setup](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)\n- [MCP Local Server Connection Guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers)\n\nAdd to your `claude_desktop_config.json`:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"grimoire\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@crack-break-make/mcp-grimoire\"]\n }\n }\n}\n```\n\n**Configuration Options**:\n\n- Environment variable`GRIMOIRE_DEBUG`: Set to `\"true\"` to enable detailed logging (useful for troubleshooting)\n\n**Restart Claude Desktop** - Grimoire MCP server is now running!\n\n**For GitHub Copilot (VS Code)**, add to `.vscode/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"grimoire\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@crack-break-make/mcp-grimoire\"]\n }\n }\n}\n```\n\n### 3. Manage Spells (CLI Commands)\n\n**For advanced users**, CLI mode is available with command arguments:\n\n```bash\n# List installed spells\nnpx @crack-break-make/mcp-grimoire@latest list\n\n# Validate a spell configuration\nnpx @crack-break-make/mcp-grimoire@latest validate ~/.grimoire/postgres.spell.yaml\n\n# Show help\nnpx @crack-break-make/mcp-grimoire@latest --help\n```\n\n### 4. Use in Claude or Copilot\n\nAfter restarting your AI agent, ask it to interact with your tools:\n\n```\nShow me all users from the database\n```\n\nGrimoire will automatically:\n\n- Match your query to the right spell (\"postgres\"), if you configured it\n- Spawn the MCP server with authentication\n- Provide tools to Claude/Copilot\n- Inject steering guidance for best practices\n\n---\n\n## ๐ŸŽญ Dual-Mode Operation\n\nMCP Grimoire intelligently detects how it's being called using a **3-step detection strategy**:\n\n| Mode | How It's Called | Purpose | Who Uses It |\n| ------------------- | ----------------------------------- | --------------------------------- | ------------------------------------------------ |\n| **MCP Server** | From `mcp.json` with stdio pipes | Runs as MCP gateway for AI agents | Claude Desktop / Copilot spawns it automatically |\n| **Interactive CLI** | From terminal with `create` command | Easy spell creation with wizard | โญ **All users - recommended!** |\n| **Advanced CLI** | From terminal with other arguments | Manage spell configurations | โš ๏ธ Power users only |\n\n---\n\n## ๐Ÿ“ฆ How It Works\n\n### High-Level Flow\n\n```\nUser Query โ†’ Claude analyzes intent โ†’ resolve_intent(query) โ†’\nGrimoire matches keywords/semantics โ†’ Spawns relevant MCP server โ†’\nInjects steering โ†’ tools/list_changed โ†’ Claude sees tools + guidance โ†’\nExecutes with best practices โ†’ After 5 turns idle โ†’ Kill server\n```\n\n### Architecture Diagram\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Claude Desktop / Copilot โ”‚\nโ”‚ Maintains conversation state โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ stdio (MCP Protocol)\n โ”‚\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ GRIMOIRE GATEWAY SERVER โ”‚\nโ”‚ - Intent Resolution (hybrid) โ”‚\nโ”‚ - Process Lifecycle Management โ”‚\nโ”‚ - Tool Routing โ”‚\nโ”‚ - Steering Injection โ”‚\nโ”‚ - Authentication Handling โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ stdio/http โ”‚ sse/http\n โ”‚ + auth โ”‚ + auth\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Postgres โ”‚ โ”‚ Stripe โ”‚ ... (spawned on-demand)\nโ”‚ MCP Server โ”‚ โ”‚ MCP Serverโ”‚ with auth headers\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n```\n\n### Key Components\n\n**1. Intent Resolution (Hybrid Approach)**\n\n- **Keyword Matching**: Exact and fuzzy matching on spell keywords\n- **Semantic Search**: Embedding-based similarity (MessagePack storage)\n- **Confidence Scoring**: 0.0-1.0 scale determines auto-spawn vs alternatives\n- **Auto-generation**: Probe feature extracts keywords from tool names\n\n**2. Process Lifecycle Management**\n\n- **On-Demand Spawning**: Servers start only when confidence โ‰ฅ 0.85\n- **Usage Tracking**: Every tool call updates `lastUsedTurn`\n- **5-Turn Inactivity**: Automatic cleanup after 5 idle conversational turns\n- **Graceful Shutdown**: SIGTERM โ†’ wait โ†’ SIGKILL if needed\n\n**3. Authentication Pipeline**\n\n- **Environment Expansion**: `${VAR}` syntax resolves from shell environment\n- **Header Building**: Constructs Bearer, Basic, or custom auth headers\n- **Secure Storage**: Credentials never logged literally (masked as `***`)\n- **OAuth Support**: \\ud83d\\udea7 Planned for future release (not yet implemented)\n - For now, use Bearer tokens obtained manually for OAuth scenarios\n\n**4. Tool Routing**\n\n- **Transparent Proxying**: Routes tool calls to appropriate spawned servers\n- **MCP Protocol**: Stdio, SSE, or HTTP transport based on spell config\n- **Error Handling**: Graceful fallbacks with detailed error messages\n\n**5. Steering Injection**\n\n- **Best Practices**: Injects expert guidance into tool descriptions\n- **Schema Context**: Embeds database schemas, API limits, security rules\n- **Auto-generation**: Probe discovers tools and creates contextual steering\n\n### Multi-Tier Intent Resolution\n\nGrimoire uses a **confidence-based approach** to decide when to auto-spawn vs ask for clarification:\n\n| Tier | Confidence | Behavior | Example |\n| ---------- | ---------- | -------------------------- | --------------------------------------------- |\n| **High** | โ‰ฅ 0.85 | **Auto-spawn** immediately | \"query postgres\" โ†’ Instant activation |\n| **Medium** | 0.50-0.84 | **Return alternatives** | \"check database\" โ†’ [postgres, mysql, mongodb] |\n| **Low** | 0.30-0.49 | **Weak matches** | \"analyze data\" โ†’ 5 weak matches |\n| **None** | < 0.30 | **Not found** | \"launch rocket\" โ†’ Error + available spells |\n\n**70% of queries** hit high confidence (zero-friction UX)
\n**20% of queries** hit medium confidence (AI agent picks from context)
\n**10% of queries** need clarification\n\n---\n\n## ๐Ÿง™ Creating Your First Spell\n\nA \"spell\" is a YAML configuration file that tells Grimoire how to spawn and use an MCP server.\n\n### Interactive Creation (Recommended for All Users)\n\n**This is the primary way to create spells** - the wizard makes it easy:\n\n```bash\n# Run without installation (recommended)\nnpx @crack-break-make/mcp-grimoire create\n\n# OR install globally first, then use short command\nnpm install -g @crack-break-make/mcp-grimoire\ngrimoire create\n```\n\nThe interactive wizard guides you through:\n\n1. **Spell name** (e.g., `postgres`, `github-api`, `weather-service`)\n2. **Transport type** (stdio, SSE, or HTTP)\n3. **Server configuration** (command/args for stdio, URL for HTTP/SSE)\n4. **Authentication** (No auth, Bearer token, Basic auth)\n5. **Environment variables** (for secrets and credentials)\n6. **Server validation** (automatic - probes server and auto-generates config)\n\n**Probing is automatic** - the wizard will:\n\n- โœ… Connect to the server with your authentication\n- โœ… Validate the server actually works\n- โœ… Auto-generate keywords from discovered tool names\n- โœ… Create intelligent steering instructions\n- โœ… Discover tool schemas and parameters\n- โœ… **Prevent spell creation if server can't be reached** (keeps your folder clean!)\n\n### Manual Creation Examples (Advanced Users Only)\n\n**โš ๏ธ Most users should use interactive mode above.** Manual creation is for power users who want full control.\n\n#### Example 1: Stdio Server (No Authentication)\n\nCreate `(user.home)/.grimoire/postgres.spell.yaml`:\n\n```yaml\nname: postgres\nversion: 1.0.0\ndescription: PostgreSQL database operations\n\nserver:\n transport: stdio\n command: npx\n args:\n - '-y'\n - '@modelcontextprotocol/server-postgres'\n env:\n DATABASE_URL: postgresql://user:pass@localhost/db\n\nkeywords:\n - database\n - sql\n - query\n - postgres\n - tables\n - users\n\nsteering: |\n # Database Schema\n Tables:\n - users (id uuid, email string, created_at timestamp)\n - orders (id uuid, user_id uuid, total decimal)\n\n # Security Rules\n ALWAYS use parameterized queries:\n โœ“ query_database('SELECT * FROM users WHERE id = $1', [id])\n โœ— 'SELECT * FROM users WHERE id = ' + id (SQL INJECTION!)\n\n # Performance Tips\n - Use LIMIT to avoid scanning millions of rows\n - created_at is indexed, use for date filtering\n```\n\n#### Example 2: HTTP Server (Bearer Token Authentication)\n\nCreate `(user.home)/.grimoire/weather-api.spell.yaml`:\n\n```yaml\nname: weather-api\nversion: 1.0.0\ndescription: Weather forecast and current conditions\n\nserver:\n transport: http\n url: http://localhost:8000/mcp\n auth:\n type: bearer\n token: ${WEATHER_API_KEY} # From environment variable\n\nkeywords:\n - weather\n - forecast\n - temperature\n - conditions\n - climate\n\nsteering: |\n # API Usage\n - Rate limit: 1000 calls/day\n - Forecast available: 7 days ahead\n - Historical data: Not available\n\n # Best Practices\n - Cache forecast results (updated hourly)\n - Use city name or coordinates\n - Check units: imperial (ยฐF) or metric (ยฐC)\n```\n\n#### Example 3: SSE Server (Custom Headers Authentication)\n\nCreate `(user.home)/.grimoire/github-api.spell.yaml`:\n\n```yaml\nname: github-api\nversion: 1.0.0\ndescription: GitHub repository and issue management\n\nserver:\n transport: sse\n url: http://localhost:8001/sse\n headers:\n X-GitHub-Token: ${GITHUB_PERSONAL_ACCESS_TOKEN}\n Accept: application/vnd.github.v3+json\n\nkeywords:\n - github\n - repository\n - repo\n - issues\n - pull\n - requests\n - commits\n\nsteering: |\n # GitHub API Guidelines\n - Use full repository names: owner/repo\n - Rate limit: 5000 requests/hour (authenticated)\n - Always check permissions before write operations\n\n # Security Best Practices\n - Never hardcode tokens (use environment variables)\n - Use fine-grained tokens when possible\n - Minimum required scopes: repo, read:user\n```\n\n**Note**: For most real-world scenarios, use the interactive wizard (`create` without args) instead of manually writing YAML files. The examples above are for reference only.\n\n### Environment Variables\n\nFor servers requiring authentication, **always use environment variable expansion** in your spell files:\n\n```yaml\nserver:\n env:\n # Database connections\n DATABASE_URL: ${DATABASE_URL}\n POSTGRES_PASSWORD: ${DB_PASSWORD}\n\n # API keys\n GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_PAT}\n WEATHER_API_KEY: ${WEATHER_KEY}\n STRIPE_SECRET_KEY: ${STRIPE_SECRET}\n\n # OAuth credentials\n OAUTH_CLIENT_ID: ${ENTERPRISE_CLIENT_ID}\n OAUTH_CLIENT_SECRET: ${ENTERPRISE_SECRET}\n```\n\n**Setting Environment Variables**:\n\nCreate a `.env` file at `(user.home)/.grimoire/.env` with your secrets:\n\n```bash\n# (user.home)/.grimoire/.env\nGITHUB_PAT=ghp_your_token_here\nWEATHER_KEY=your_weather_api_key\nDATABASE_URL=postgresql://user:pass@localhost/db\nDB_PASSWORD=your_secure_password\nSTRIPE_SECRET=sk_test_your_stripe_key\nENTERPRISE_CLIENT_ID=your_oauth_client_id\nENTERPRISE_SECRET=your_oauth_client_secret\n```\n\n**โš ๏ธ Important**: The `.env` file is automatically loaded by MCP Grimoire at startup. Never commit this file to version control.\n\n**Spell File Location** (all platforms):\n\n- `(user.home)/.grimoire/` (follows AI Agents convention)\n - **macOS**: `/Users/username/.grimoire/`\n - **Windows**: `C:\\Users\\username\\.grimoire\\`\n - **Linux**: `/home/username/.grimoire/`\n\n---\n\n## ๐Ÿ”ฎ Supported MCP Transports\n\n### โœ… Stdio (Fully Supported)\n\nFor local MCP servers spawned as child processes (most common):\n\n```yaml\nserver:\n transport: stdio\n command: npx\n args:\n - '-y'\n - '@modelcontextprotocol/server-postgres'\n```\n\nExamples:\n\n- `@modelcontextprotocol/server-postgres`\n- `@modelcontextprotocol/server-github`\n- `@cap-js/mcp-server`\n\n### โœ… SSE (Fully Supported)\n\nFor real-time MCP servers using Server-Sent Events:\n\n```yaml\nserver:\n transport: sse\n url: https://your-sse-url/sse\n```\n\n### โœ… HTTP (Fully Supported)\n\nFor REST-like MCP servers:\n\n```yaml\nserver:\n transport: http\n url: https://your-http-url/mcp\n```\n\n---\n\n## ๐Ÿ” Authentication Support\n\nGrimoire supports comprehensive authentication for secure MCP server connections:\n\n### โœ… No Authentication\n\nFor public or local servers with no auth requirements:\n\n```yaml\nserver:\n transport: stdio\n command: npx\n args: ['-y', '@modelcontextprotocol/server-filesystem']\n # No auth configuration needed\n```\n\n### โœ… API Key / Bearer Token\n\nFor servers requiring API key authentication (sent as `Authorization: Bearer` header):\n\n```yaml\nserver:\n transport: http\n url: http://localhost:8000/mcp\n auth:\n type: bearer\n token: ${MY_API_KEY} # Environment variable expansion\n```\n\n**Common for**: Weather APIs, News services, Analytics platforms\n\n### โœ… Basic Authentication\n\nFor servers using username/password authentication:\n\n```yaml\nserver:\n transport: http\n url: http://localhost:8001/mcp\n auth:\n type: basic\n username: ${DB_USERNAME}\n password: ${DB_PASSWORD}\n```\n\n**Note**: Basic auth is sent as a Bearer token (Base64-encoded `username:password`) for FastMCP server compatibility.\n\n### โœ… Security Keys (Custom Headers)\n\nFor servers requiring custom authentication headers (e.g., GitHub, Brave):\n\n```yaml\nserver:\n transport: sse\n url: http://localhost:8002/sse\n headers:\n X-GitHub-Token: ${GITHUB_TOKEN}\n X-Brave-Key: ${BRAVE_API_KEY}\n X-Custom-Auth: ${CUSTOM_SECRET}\n```\n\n**Common for**: GitHub API, Brave Search, custom enterprise APIs\n\n### ๐Ÿšง OAuth 2.0 Flows (Planned for Future Release)\n\nOAuth 2.0 authentication flows are **NOT YET IMPLEMENTED**. They are planned for a future release.\n\n**Planned OAuth Flows** (not available yet):\n\n#### OAuth 2.0 Client Credentials (Planned)\n\n```yaml\nserver:\n transport: http\n url: http://localhost:8003/mcp\n auth:\n type: client_credentials\n clientId: ${OAUTH_CLIENT_ID}\n clientSecret: ${OAUTH_CLIENT_SECRET}\n tokenUrl: https://oauth.example.com/token\n scope: read:data write:data # Optional\n```\n\n**Status**: ๐Ÿšง **Planned** - Not yet implemented\n\n#### OAuth 2.0 Private Key JWT (Planned)\n\n```yaml\nserver:\n transport: http\n url: http://localhost:8004/mcp\n auth:\n type: private_key_jwt\n clientId: ${OAUTH_CLIENT_ID}\n privateKey: ${PRIVATE_KEY_PEM} # PEM format\n tokenUrl: https://oauth.example.com/token\n algorithm: RS256 # Optional: RS256 (default), RS384, RS512, ES256, ES384, ES512\n```\n\n**Status**: ๐Ÿšง **Planned** - Not yet implemented\n\n#### OAuth 2.0 Static Private Key JWT (Planned)\n\nFor pre-generated JWT tokens with static assertions:\n\n```yaml\nserver:\n transport: http\n url: http://localhost:8005/mcp\n auth:\n type: static_private_key_jwt\n clientId: ${OAUTH_CLIENT_ID}\n privateKey: ${PRIVATE_KEY_PEM}\n tokenUrl: https://oauth.example.com/token\n staticClaims:\n sub: service-account@example.com\n aud: https://api.example.com\n```\n\n**Status**: ๐Ÿšง **Planned** - Not yet implemented\n\n#### OAuth 2.0 Authorization Code (Planned)\n\nInteractive OAuth flow with browser-based authentication:\n\n```yaml\nserver:\n transport: http\n url: http://localhost:8006/mcp\n auth:\n type: authorization_code\n clientId: ${OAUTH_CLIENT_ID}\n clientSecret: ${OAUTH_CLIENT_SECRET}\n authorizationUrl: https://oauth.example.com/authorize\n tokenUrl: https://oauth.example.com/token\n redirectUri: http://localhost:3000/callback\n```\n\n**Status**: ๐Ÿšง **Planned** - Requires browser interaction flow (future release)\n\n### Summary of Auth Support\n\n| Authentication Type | Status | Use Case |\n| ------------------------ | ---------- | ------------------------------ |\n| No Auth | โœ… Working | Public/local servers |\n| Bearer Token | โœ… Working | API keys, access tokens |\n| Basic Auth | โœ… Working | Username/password servers |\n| Security Keys | โœ… Working | Custom headers (GitHub, Brave) |\n| OAuth Client Credentials | ๐Ÿšง Planned | Server-to-server OAuth |\n| OAuth Private Key JWT | ๐Ÿšง Planned | Enhanced security OAuth |\n| OAuth Authorization Code | ๐Ÿšง Planned | Interactive browser flow |\n\n**For now, use Bearer Token or Security Keys for most OAuth scenarios** by obtaining tokens manually.\n\n---\n\n## โšก When Servers Are Spawned and Killed\n\n### Spawn Triggers\n\n**1. High Confidence Match (โ‰ฅ0.85)**\n\n```\nUser: \"query my postgres database\"\nโ†’ resolve_intent matches \"postgres\" with 0.94 confidence\nโ†’ Immediate spawn + return tools\nโ†’ Time: 200-300ms\n```\n\n**2. Manual Activation**\n\n```\nUser: \"check my database\"\nโ†’ resolve_intent returns alternatives: [postgres, mysql, mongodb]\nโ†’ Claude (or user) calls: activate_spell({ name: \"postgres\" })\nโ†’ Spawn specified spell\nโ†’ Time: 200-300ms\n```\n\n**3. Already Active**\n\n```\nโ†’ Just update usage tracking\nโ†’ Time: ~5ms (no spawn overhead)\n```\n\n### Kill Triggers (5-Turn Inactivity)\n\nAfter **every tool call**, Grimoire checks:\n\n```\nIf (currentTurn - lastUsedTurn) >= 5:\n โ†’ Kill process\n โ†’ Unregister tools\n โ†’ Send tools/list_changed notification\n```\n\n**Real-World Example** (E-commerce workflow):\n\n| Turn | Action | Active Spells | Event |\n| ---- | ---------------- | ---------------------------- | --------------------------------- |\n| 1-3 | Database queries | `[postgres]` | โœ… Postgres spawned |\n| 4-7 | Process payments | `[postgres, stripe]` | โœ… Stripe spawned |\n| 8 | Deploy CAP app | `[postgres, stripe, cap-js]` | โœ… Cap-js spawned |\n| 9 | CAP deployment | `[stripe, cap-js]` | โŒ Postgres killed (6 turns idle) |\n| 14 | CAP testing | `[cap-js]` | โŒ Stripe killed (7 turns idle) |\n\n**Result**: 3 spells โ†’ 1 spell (67% token reduction from peak)\n\n---\n\n## ๐Ÿ› ๏ธ CLI Commands (Run in Terminal)\n\n**Important**: CLI commands run in your **terminal**, not in Claude Desktop. The MCP server runs inside Claude automatically.\n\n### `npx @crack-break-make/mcp-grimoire@latest create`\n\nCreate new spell configurations with interactive wizard:\n\n```bash\n# Interactive mode (guided) - RECOMMENDED\nnpx @crack-break-make/mcp-grimoire@latest create\n\n# With server validation (auto-generates steering)\nnpx @crack-break-make/mcp-grimoire@latest create --probe\n\n# Non-interactive mode\nnpx @crack-break-make/mcp-grimoire@latest create \\\n -n postgres \\\n -t stdio \\\n --command npx \\\n --args \"-y\" \"@modelcontextprotocol/server-postgres\"\n\n# With environment variables (for authenticated servers)\nnpx @crack-break-make/mcp-grimoire@latest create \\\n -n github \\\n -t stdio \\\n --command npx \\\n --args \"-y\" \"@modelcontextprotocol/server-github\" \\\n --env \"GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}\"\n```\n\n**Optional**: Install globally for shorter command:\n\n```bash\nnpm install -g @crack-break-make/mcp-grimoire@latest\n\n# Now use short form:\ngrimoire create\ngrimoire list\n```\n\n**Features**:\n\n- Validates MCP server works before creating config\n- Auto-generates keywords from tool names\n- Creates intelligent steering instructions\n- Supports environment variables for authenticated servers\n- Supports all transport types (stdio, SSE, HTTP)\n\n### `npx @crack-break-make/mcp-grimoire@latest list`\n\nList all installed spells:\n\n```bash\n# Simple list\nnpx @crack-break-make/mcp-grimoire@latest list\n\n# Verbose output with details\nnpx @crack-break-make/mcp-grimoire@latest list -v\n```\n\n**Output**:\n\n```\n๐Ÿ“š Spells in ~/.grimoire\n\n ๐Ÿ”ฎ postgres [stdio ] (8 keywords)\n ๐Ÿ”ฎ stripe [stdio ] (12 keywords)\n ๐Ÿ”ฎ github-api [stdio ] (15 keywords)\n\nโœ“ Total: 3 spells\n```\n\n### `npx @crack-break-make/mcp-grimoire@latest validate`\n\nValidate spell configuration:\n\n```bash\nnpx @crack-break-make/mcp-grimoire@latest validate ~/.grimoire/postgres.spell.yaml\n```\n\n**Checks**:\n\n- Required fields (name, keywords, server.command/url)\n- Field types and formats\n- Minimum 3 keywords\n- Transport-specific requirements\n\n---\n\n## ๐ŸŽจ Using with AI Agents\n\n### Claude Desktop\n\n**How It Works**:\n\n1. User asks: \"Show users from database\"\n2. Claude sees `resolve_intent` tool (always available)\n3. Claude calls: `resolve_intent({ query: \"show users from database\" })`\n4. Grimoire spawns postgres, injects steering, returns tools\n5. Claude receives `tools/list_changed` notification\n6. Claude calls: `query_database({ query: \"SELECT * FROM users\" })`\n7. After 5 turns idle โ†’ Grimoire kills postgres automatically\n\n**Key Insight**: Claude doesn't know about Grimoire's complexity - it just sees tools appearing/disappearing via MCP protocol notifications.\n\n### GitHub Copilot (VS Code)\n\nSame workflow as Claude Desktop. Add to `settings.json`:\n\n```json\n{\n \"servers\": {\n \"grimoire\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@crack-break-make/mcp-grimoire\"]\n }\n }\n}\n```\n\n---\n\n## ๐Ÿ“Š Token Savings Breakdown\n\n### Traditional MCP (Baseline)\n\n```\nAll 50 servers spawned at startup:\n- postgres tools (8 tools ร— 200 tokens) = 1,600 tokens\n- stripe tools (12 tools ร— 200 tokens) = 2,400 tokens\n- github tools (15 tools ร— 200 tokens) = 3,000 tokens\n- ... 47 more servers\n= ~40,000 tokens per conversation\n```\n\n### Grimoire (Multi-Tier Strategy)\n\n**Weighted Average Calculation**:\n\n```\nHigh confidence (70%): 1,000 tokens (selected tools only)\nMedium confidence (20%): 1,500 tokens (3 alternatives + tools)\nLow confidence (8%): 2,000 tokens (5 weak matches + tools)\nNo match (2%): 300 tokens (error + available spells)\n\nAverage = 0.70ร—1000 + 0.20ร—1500 + 0.08ร—2000 + 0.02ร—300\n = 700 + 300 + 160 + 6\n = 1,166 tokens\n```\n\n**Savings**: `(40,000 - 1,166) / 40,000 = 97.1%` ๐ŸŽ‰\n\n---\n\n## ๐Ÿค Contributing\n\nWe welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.\n\n### Getting Started\n\n**1. Fork & Clone**\n\n```bash\n# Fork on GitHub, then clone\ngit clone https://github.com/YOUR_USERNAME/mcp-grimoire.git\ncd mcp-grimoire\n\n# Install dependencies\npnpm install\n```\n\n**2. Create a Branch**\n\n```bash\ngit checkout -b feature/my-awesome-feature\n```\n\n**3. Make Changes**\n\nFollow our coding principles:\n\n- **YAGNI**: Implement only what's needed now\n- **DRY**: Don't repeat yourself\n- **SRP**: Single Responsibility Principle\n- **SOLID**: Follow SOLID principles\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for comprehensive development guidelines.\n\n**4. Run Tests**\n\n```bash\n# Run all tests\npnpm test\n\n# Run with coverage\npnpm test:coverage\n```\n\n**5. Commit Changes**\n\nWe use [Conventional Commits](https://www.conventionalcommits.org/):\n\n```bash\n# Format\ntype(scope): short description\n\n# Examples\nfeat(intent): add semantic search with embeddings\nfix(lifecycle): prevent orphaned child processes\ndocs(readme): add contributing section\ntest(gateway): add multi-tier resolution tests\n```\n\n**6. Submit Pull Request**\n\n```bash\ngit push origin feature/my-awesome-feature\n```\n\nThen open a PR on GitHub with:\n\n- Clear description of changes\n- Link to related issues\n- Screenshots/examples if applicable\n\n### Development Commands\n\n```bash\n# Development server (hot reload)\npnpm dev\n\n# Build TypeScript\npnpm build\n\n# Linting\npnpm lint # Check for issues\npnpm lint:fix # Auto-fix issues\n\n# Formatting\npnpm format # Format all files with Prettier\n\n# Type checking\npnpm type-check # Check TypeScript types\n```\n\n### Project Structure\n\n```\nmcp-grimoire/\nโ”œโ”€โ”€ src/\nโ”‚ โ”œโ”€โ”€ core/ # Domain models (types, configs)\nโ”‚ โ”œโ”€โ”€ application/ # Business logic (intent, lifecycle)\nโ”‚ โ”œโ”€โ”€ infrastructure/ # External systems (file, embeddings)\nโ”‚ โ”œโ”€โ”€ presentation/ # Gateway server, tool routing\nโ”‚ โ”œโ”€โ”€ cli/ # CLI commands, templates\nโ”‚ โ””โ”€โ”€ utils/ # Shared utilities\nโ”œโ”€โ”€ tests/\nโ”‚ โ””โ”€โ”€ fixtures/ # Test spell configurations\nโ”œโ”€โ”€ docs/\nโ”‚ โ”œโ”€โ”€ adr/ # Architecture Decision Records\nโ”‚ โ””โ”€โ”€ architecture.md # System architecture\n```\n\n### Creating Architecture Decision Records (ADRs)\n\nFor significant architectural decisions, create an ADR:\n\n```bash\n# Use the adr-generator skill\n/adr-generator --title \"Use Hybrid Intent Resolution\" --status proposed\n```\n\nSee [docs/adr/README.md](./docs/adr/README.md) for guidelines.\n\n### Running Integration Tests\n\n```bash\n# Requires test servers to be available\npnpm test:integration\n\n# Run specific integration test\npnpm test src/presentation/__tests__/gateway-real-workflow.integration.test.ts\n```\n\n### Code Quality Standards\n\nWe maintain high code quality through:\n\n- โœ… 80%+ test coverage (unit + integration)\n- โœ… Strict TypeScript (`strict: true`)\n- โœ… ESLint + Prettier formatting\n- โœ… No `any` types (enforced by linter)\n- โœ… Comprehensive error handling\n\n### Need Help?\n\n- ๐Ÿ’ฌ [Join Discussions](https://github.com/crack-break-make/mcp-grimoire/discussions)\n- ๐Ÿ› [Report Issues](https://github.com/crack-break-make/mcp-grimoire/issues)\n- ๐Ÿ“ง Email: [Mohan Sharma](mailto:crack.break.make@gmail.com)\n\n---\n\n## โ“ FAQ & Troubleshooting\n\n### AI Agent Not Showing `resolve_intent` Tool\n\n**Problem**: GitHub Copilot (VS Code) or other AI agents cache tools aggressively. After Grimoire spawns and registers new tools, the AI agent may not see them immediately, including the critical `resolve_intent` tool.\n\n**Solution**: Explicitly prompt the AI agent to refresh its tool list:\n\n```\nPlease call the tools/list API to refresh available tools, then use the resolve_intent tool to search for [your query].\n```\n\n**Why this happens**:\n\n- MCP clients cache tool lists for performance\n- The `tools/list_changed` notification may not trigger immediate refresh in all clients\n- This is a known limitation of some MCP client implementations (not a Grimoire bug)\n\n**Alternative approach**: Restart the AI agent (e.g., reload VS Code window) to force tool cache refresh.\n\n---\n\n## ๐Ÿ“– Documentation\n\n- [Architecture Overview](./docs/architecture.md)\n- [Contributing Guide](./CONTRIBUTING.md)\n- [Architecture Decision Records](./docs/adr/README.md)\n- [Intent Resolution Strategy](./docs/intent-resolution-solution.md)\n- [Turn-Based Lifecycle](./docs/turn-based-lifecycle-explained.md)\n\n---\n\n## ๐Ÿ“ License\n\nISC ยฉ [Mohan Sharma](https://github.com/crack-break-make)\n\n---\n\n## ๐Ÿ”— Links\n\n- **GitHub**: [crack-break-make/mcp-grimoire](https://github.com/crack-break-make/mcp-grimoire)\n- **npm**: [@crack-break-make/mcp-grimoire](https://www.npmjs.com/package/@crack-break-make/mcp-grimoire)\n- **Issues**: [Report bugs or request features](https://github.com/crack-break-make/mcp-grimoire/issues)\n- **Discussions**: [Join the community](https://github.com/crack-break-make/mcp-grimoire/discussions)\n\n---\n\n**Made with โค๏ธ by [Mohan Sharma](https://github.com/crack-break-make)**\n\n_Special thanks to the MCP community and all contributors!_\n","readmeFilename":"README.md"}