您的MCP服务器智能拼写本 -延迟加载编排，节省97%的令牌

![TypeScript](.) ![License](.) ](https://www.npmjs.com/package/@crack-break-make/mcp-grimoire)

______________________________________________________________________

📺 视频教程

刚加入MCP Grimoire？ 观看此全面演练：

![MCP Grimoire Tutorial](https://youtu.be/1N0RN4f5EuA)

🎥 在YouTube上观看：MCP Grimoire-完整的设置和使用指南

______________________________________________________________________

🎯 什么是MCP Grimoire？

MCP Grimoire 是一个智能编排器模型上下文协议（MCP）服务器。它充当人工智能代理（如Claude Desktop、GitHub Copilot）和MCP工具之间的智能网关，解决人工智能驱动的开发工作流程中的关键性能和可用性问题。

问题

传统的MCP实现存在三个关键问题：

1.上下文过载（令牌浪费）💸

启动时加载50多个工具会消耗40000多个代币
降低人工智能性能并增加API成本
导致响应较慢和工具选择混乱

2.缺少领域专业知识🤷

MCP工具缺乏上下文指导和最佳实践
用户必须手动提示输入安全模式
导致漏洞和使用不一致

3.插件开发复杂性🔧

创建MCP插件没有标准化的模式
难以维护和扩展
支离破碎的生态系统

解决方案

MCP Grimoire实现 代币减少97% 通过：

✅ 延迟加载 -仅在需要时生成MCP服务器，而不是在启动时生成

✅ 意图驱动的发现 -通过混合关键字+语义搜索将查询与工具匹配

✅ 积极清理 -在5次不活动后杀死不活动的服务器

✅ 转向喷射 -将最佳实践直接嵌入到工具描述中

✅ 透明操作 -克劳德不知道事情的复杂性

结果：40000个代币→ 1,平均166个令牌（每次查询约0.20美元→约0.006美元）

______________________________________________________________________

🚀 快速开始

先决条件

Node.js 22+（用于运行MCP服务器）
克劳德桌面 或 GitHub Copilot （任何支持MCP的AI代理）
基本了解命令行工具

设置工作流

1. Create Spells (Terminal)      →  2. Configure Grimoire (mcp.json)  →  3. Use in AI Agent
   npx mcp-grimoire create           Add to Claude/Copilot config          Ask questions naturally
   - Interactive wizard              - Grimoire runs as MCP gateway        - Servers spawn on-demand
   - Auto-probes server              - Debug with GRIMOIRE_DEBUG           - Auto-cleanup after 5 turns idle

1.首先创建拼写（在终端中）

⚠️ 重要：在配置MCP服务器之前，请务必创建法术！

运行交互式向导（建议所有用户使用）：

npx @crack-break-make/mcp-grimoire@latest create

向导将：

✅ 指导您完成每个配置步骤
✅ 自动探测服务器（验证连接）
✅ 从发现的工具自动生成关键字
✅ 创建智能转向指令
✅ 如果无法访问服务器，则阻止拼写创建
✅ 将拼写保存到 (user.home)/.grimoire/yourspell.spell.yaml

为什么调查很重要：如果探测失败，则不会创建咒语（防止破坏配置）。

列出你的咒语: npx @crack-break-make/mcp-grimoire@latest list

2.配置MCP服务器（在Claude Desktop/GitHub Copilot中）

只有在创造法术之后，将Grimoire添加到您的MCP配置中。

📚 了解有关MCP配置的更多信息:

添加到您的 claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "grimoire": {
      "command": "npx",
      "args": ["-y", "@crack-break-make/mcp-grimoire"]
    }
  }
}

配置选项:

环境变量GRIMOIRE_DEBUG：设置为 "true" 启用详细日志记录（有助于故障排除）

重新启动克劳德桌面 -Grimoire MCP服务器现在正在运行！

GitHub副本（VS代码），添加到 .vscode/mcp.json:

{
  "mcpServers": {
    "grimoire": {
      "command": "npx",
      "args": ["-y", "@crack-break-make/mcp-grimoire"]
    }
  }
}

3.管理拼写（CLI命令）

对于高级用户，CLI模式可用于命令参数：

# List installed spells
npx @crack-break-make/mcp-grimoire@latest list

# Validate a spell configuration
npx @crack-break-make/mcp-grimoire@latest validate ~/.grimoire/postgres.spell.yaml

# Show help
npx @crack-break-make/mcp-grimoire@latest --help

4.在Claude或Copilot中使用

重启AI代理后，让它与您的工具进行交互：

Show me all users from the database

Grimoire将自动：

如果您配置了查询，请将其与正确的拼写（“postgres”）匹配
为MCP服务器生成身份验证
为Claude/Copilot提供工具
注入转向指导以获得最佳实践

______________________________________________________________________

🎭 双模式操作

MCP Grimoire使用 三步检测策略:

模式	如何命名	目的	谁使用它
MCP 服务器	从 `mcp.json` 使用stdio管道	作为AI代理的MCP网关运行	Claude Desktop/Copilot自动生成它
交互式CLI	从终端与 `create` command	使用向导轻松创建法术	⭐ 所有用户-推荐！
高级CLI	从带有其他参数的终端	管理拼写配置	⚠️ 仅限高级用户

______________________________________________________________________

📦 运作原理

高水位流量

User Query → Claude analyzes intent → resolve_intent(query) →
Grimoire matches keywords/semantics → Spawns relevant MCP server →
Injects steering → tools/list_changed → Claude sees tools + guidance →
Executes with best practices → After 5 turns idle → Kill server

架构图

┌──────────────────────────────────────┐
│      Claude Desktop / Copilot        │
│  Maintains conversation state        │
└──────────────┬───────────────────────┘
               │ stdio (MCP Protocol)
               │
┌──────────────▼───────────────────────┐
│      GRIMOIRE GATEWAY SERVER         │
│  - Intent Resolution (hybrid)        │
│  - Process Lifecycle Management      │
│  - Tool Routing                      │
│  - Steering Injection                │
│  - Authentication Handling           │
└──────┬──────────────┬────────────────┘
       │ stdio/http   │ sse/http
       │ + auth       │ + auth
┌──────▼─────┐  ┌────▼──────┐
│  Postgres  │  │  Stripe   │  ... (spawned on-demand)
│ MCP Server │  │ MCP Server│       with auth headers
└────────────┘  └───────────┘

关键组件

1.意图解析（混合方法）

关键词匹配：拼写关键字的精确和模糊匹配
语义搜索：基于嵌入的相似性（MessagePack存储）
信心评分：0.0-1.0比例决定自动生成与备选方案
自动生成：探测功能从工具名称中提取关键字

2.过程生命周期管理

按需产卵：服务器仅在置信度≥0.85时启动
使用情况跟踪：每次工具调用都会更新 lastUsedTurn
5转不活动：5次空闲会话回合后自动清理
优雅关闭：SIGTERM→ wait → SIGKILL（如果需要）

3.身份验证管道

环境拓展: ${VAR} 从shell环境解析语法
海德大厦：构造Bearer、Basic或自定义身份验证标头
安全存储：凭据从未按字面意思记录（掩码为 ***)
OAuth支持：\\ud83d\\udea7计划在未来发布（尚未实施）

- 目前，在OAuth场景中使用手动获得的Bearer令牌

4.刀具路径

透明代理：将工具调用路由到相应的生成服务器
MCP协议：基于拼写配置的Stdio、SSE或HTTP传输
错误处理：优雅的回退，带有详细的错误消息

5.转向喷射

最佳实践：在工具描述中注入专家指导
架构上下文：嵌入数据库架构、API限制、安全规则
自动生成：Probe发现工具并创建上下文导向

多层意图解析

Grimoire使用 基于置信度的方法 决定何时自动生成vs要求澄清：

层级	信心	行为	示例
高	≥ 0.85	自动生成立即	“查询postgres”→ 即时激活
中等	0.50-0.84	返回备选方案	“检查数据库”→ \[postgres、mysql、mongodb\]
低	0.30-0.49	弱匹配	“分析数据”→ 5 弱匹配
无	\= 5:

→ Kill process → Unregister tools → Send tools/list_changed notification


**真实世界示例** （电子商务工作流程）：

|转身|动作|活动法术|事件|
| ---- | ---------------- | ---------------------------- | --------------------------------- |
|1-3|数据库查询| `[postgres]` | ✅ Postgres诞生|
|4-7|处理付款| `[postgres, stripe]` | ✅ 条纹生成|
|8|部署CAP应用程序| `[postgres, stripe, cap-js]` | ✅ Cap js诞生|
|9|CAP部署| `[stripe, cap-js]` | ❌ Postgres被杀（6转空闲）|
|14|CAP测试| `[cap-js]` | ❌ 条纹被杀死（7转空闲）|

**结果**：3个法术→ 1 法术（从峰值减少67%的令牌）

______________________________________________________________________

## 🛠️ CLI命令（在终端中运行）

**重要**：CLI命令在您的 **终端**，不在Claude Desktop中。MCP服务器在Claude内部自动运行。

### `npx @crack-break-make/mcp-grimoire@latest create`

使用交互式向导创建新的法术配置：

Interactive mode (guided) - RECOMMENDED

npx @crack-break-make/mcp-grimoire@latest create

With server validation (auto-generates steering)

npx @crack-break-make/mcp-grimoire@latest create --probe

Non-interactive mode

npx @crack-break-make/mcp-grimoire@latest create \ -n postgres \ -t stdio \ --command npx \ --args "-y" "@modelcontextprotocol/server-postgres"

With environment variables (for authenticated servers)

npx @crack-break-make/mcp-grimoire@latest create \ -n github \ -t stdio \ --command npx \ --args "-y" "@modelcontextprotocol/server-github" \ --env "GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}"


**可选的**：全局安装以缩短命令：

npm install -g @crack-break-make/mcp-grimoire@latest

Now use short form:

grimoire create grimoire list


**特性**:

- 在创建配置之前验证MCP服务器是否正常工作
- 根据工具名称自动生成关键字
- 创建智能转向指令
- 支持经过身份验证的服务器的环境变量
- 支持所有传输类型（stdio、SSE、HTTP）

### `npx @crack-break-make/mcp-grimoire@latest list`

列出所有已安装的法术：

Simple list

npx @crack-break-make/mcp-grimoire@latest list

Verbose output with details

npx @crack-break-make/mcp-grimoire@latest list -v


**输出**:

📚 Spells in ~/.grimoire

🔮 postgres [stdio ] (8 keywords) 🔮 stripe [stdio ] (12 keywords) 🔮 github-api [stdio ] (15 keywords)

✓ Total: 3 spells


### `npx @crack-break-make/mcp-grimoire@latest validate`

验证拼写配置：

npx @crack-break-make/mcp-grimoire@latest validate ~/.grimoire/postgres.spell.yaml


**支票**:

- 必填字段（名称、关键字、server.command/url）
- 字段类型和格式
- 最少3个关键字
- 运输特定要求

______________________________________________________________________

## 🎨 与AI代理一起使用

### 克劳德桌面

**运作原理**:

1. 用户询问：“显示数据库中的用户”
1. 克劳德看到 `resolve_intent` 工具（始终可用）
1. 克劳德来电： `resolve_intent({ query: "show users from database" })`
1. Grimoire生产postgres，注入转向系统，归还工具
1. 克劳德接收 `tools/list_changed` 通知
1. 克劳德来电： `query_database({ query: "SELECT * FROM users" })`
1. 5转怠速后→ Grimoire会自动杀死postgres

**关键洞察**：Claude不知道Grimoire的复杂性——它只是通过MCP协议通知看到工具出现/消失。

### GitHub副本（VS代码）

工作流程与Claude Desktop相同。添加到 `settings.json`:

{ "servers": { "grimoire": { "command": "npx", "args": ["-y", "@crack-break-make/mcp-grimoire"] } } }


______________________________________________________________________

## 📊 代币储蓄明细

### 传统MCP（基线）

All 50 servers spawned at startup:

postgres tools (8 tools × 200 tokens) = 1,600 tokens
stripe tools (12 tools × 200 tokens) = 2,400 tokens
github tools (15 tools × 200 tokens) = 3,000 tokens
... 47 more servers

= ~40,000 tokens per conversation


### Grimoire（多层战略）

**加权平均计算**:

High confidence (70%): 1,000 tokens (selected tools only) Medium confidence (20%): 1,500 tokens (3 alternatives + tools) Low confidence (8%): 2,000 tokens (5 weak matches + tools) No match (2%): 300 tokens (error + available spells)

Average = 0.70×1000 + 0.20×1500 + 0.08×2000 + 0.02×300 = 700 + 300 + 160 + 6 = 1,166 tokens


**储蓄**: `(40,000 - 1,166) / 40,000 = 97.1%` 🎉

______________________________________________________________________

## 🤝 贡献

我们欢迎捐款！无论您是在修复错误、添加功能还是改进文档，我们都会感谢您的帮助。

### 入门指南

**1.分叉和克隆**

Fork on GitHub, then clone

git clone https://github.com/YOUR_USERNAME/mcp-grimoire.git cd mcp-grimoire

Install dependencies

pnpm install


**2.创建分支**

git checkout -b feature/my-awesome-feature


**3.进行更改**

遵循我们的编码原则：

- **雅格尼**：只实施现在需要的东西
- **不要重复自己**不要重复自己的话
- **单一职责原则**：单一责任原则
- **SOLID**：遵循SOLID原则

看 [贡献.md](./CONTRIBUTING.md) 全面的发展指南。

**4.运行测试**

Run all tests

pnpm test

Run with coverage

pnpm test:coverage


**5.提交更改**

我们使用 [约定式提交](https://www.conventionalcommits.org/):

Format

type(scope): short description

Examples

feat(intent): add semantic search with embeddings fix(lifecycle): prevent orphaned child processes docs(readme): add contributing section test(gateway): add multi-tier resolution tests


**6.提交拉取请求**

git push origin feature/my-awesome-feature


然后在GitHub上打开一个PR：

- 变更的清晰描述
- 链接到相关问题
- 屏幕截图/示例（如适用）

### 开发命令

Development server (hot reload)

pnpm dev

Build TypeScript

pnpm build

Linting

pnpm lint # Check for issues pnpm lint:fix # Auto-fix issues

Formatting

pnpm format # Format all files with Prettier

Type checking

pnpm type-check # Check TypeScript types


### 项目结构

mcp-grimoire/ ├── src/ │ ├── core/ # Domain models (types, configs) │ ├── application/ # Business logic (intent, lifecycle) │ ├── infrastructure/ # External systems (file, embeddings) │ ├── presentation/ # Gateway server, tool routing │ ├── cli/ # CLI commands, templates │ └── utils/ # Shared utilities ├── tests/ │ └── fixtures/ # Test spell configurations ├── docs/ │ ├── adr/ # Architecture Decision Records │ └── architecture.md # System architecture


### 创建架构决策记录（ADR）

对于重大的架构决策，创建ADR：

Use the adr-generator skill

/adr-generator --title "Use Hybrid Intent Resolution" --status proposed


看 [docs/adr/README.md](./docs/adr/README.md) 作为指导方针。

### 运行集成测试

Requires test servers to be available

pnpm test:integration

Run specific integration test

pnpm test src/presentation/__tests__/gateway-real-workflow.integration.test.ts


### 代码质量标准

我们通过以下方式保持高代码质量：

- ✅ 80%+测试覆盖率（单元+集成）
- ✅ 严格的TypeScript(`strict: true`)
- ✅ ESLint+预处理格式
- ✅ 不 `any` 类型（由linter强制执行）
- ✅ 全面的错误处理

### 需要帮助？

- 💬 [加入讨论](https://github.com/crack-break-make/mcp-grimoire/discussions)
- 🐛 [报告问题](https://github.com/crack-break-make/mcp-grimoire/issues)
- 📧 电子邮件： [莫汉·夏尔马](mailto:crack.break.make@gmail.com)

______________________________________________________________________

## ❓ 常见问题解答和故障排除

### AI代理未显示 `resolve_intent` 工具

**问题**GitHub Copilot（VS Code）或其他AI代理积极缓存工具。Grimoire生成并注册新工具后，AI代理可能不会立即看到它们，包括关键工具 `resolve_intent` 工具。

**解决方案**：明确提示AI代理刷新其工具列表：

Please call the tools/list API to refresh available tools, then use the resolve_intent tool to search for [your query].


**为什么会这样**:

- MCP客户端缓存工具列表以提高性能
- 这 `tools/list_changed` 通知可能不会在所有客户端中立即触发刷新
- 这是一些MCP客户端实现的已知限制（不是Grimoire错误）

**替代方法**：重新启动AI代理（例如，重新加载VS Code窗口）以强制刷新工具缓存。

______________________________________________________________________

## 📖 文档

- [架构概述](./docs/architecture.md)
- [贡献指南](./CONTRIBUTING.md)
- [架构决策记录](./docs/adr/README.md)
- [意图解决策略](./docs/intent-resolution-solution.md)
- [基于回合的生命周期](./docs/turn-based-lifecycle-explained.md)

______________________________________________________________________

## 📝 许可证

ISC© [莫汉·夏尔马](https://github.com/crack-break-make)

______________________________________________________________________

## 🔗 链接

- **GitHub**: [裂纹断裂制造/mcp grimoire](https://github.com/crack-break-make/mcp-grimoire)
- **npm**: [@裂纹断裂制造/mcp grimoire](https://www.npmjs.com/package/@crack-break-make/mcp-grimoire)
- **问题**: [报告错误或请求功能](https://github.com/crack-break-make/mcp-grimoire/issues)
- **讨论**: [加入社区](https://github.com/crack-break-make/mcp-grimoire/discussions)

______________________________________________________________________

**由...制作❤️ 通过 [莫汉·夏尔马](https://github.com/crack-break-make)**

_特别感谢MCP社区和所有贡献者！_

MCP Grimoire

快速接入

详细介绍

📺 视频教程

🎯 什么是MCP Grimoire？

问题

解决方案

🚀 快速开始

先决条件

设置工作流

1.首先创建拼写（在终端中）

2.配置MCP服务器（在Claude Desktop/GitHub Copilot中）

3.管理拼写（CLI命令）

4.在Claude或Copilot中使用

🎭 双模式操作

📦 运作原理

高水位流量

架构图

关键组件

多层意图解析

Interactive mode (guided) - RECOMMENDED

With server validation (auto-generates steering)

Non-interactive mode

With environment variables (for authenticated servers)

Now use short form:

Simple list

Verbose output with details

Fork on GitHub, then clone

Install dependencies

Run all tests

Run with coverage

Format

Examples

Development server (hot reload)

Build TypeScript

Linting

Formatting

Type checking

Use the adr-generator skill

Requires test servers to be available

Run specific integration test

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP