MCP上下文保护程序
一个强大的工具，可以分析模型上下文协议（MCP）服务器，并在它们周围创建智能的LLM驱动的包装器。将任何MCP服务器转换为能够理解自然语言请求并自动协调复杂多工具操作的专家系统。
目录
- 克劳德桌面 - 克劳德代码 - 其他与MCP兼容的AI代理
特性
- 🔍 自动服务器分析：从任何MCP服务器发现工具、资源和提示
- 🤖 LLM动力协调：使用OpenAI智能规划和执行多工具操作
- 🎯 专家系统生成：将服务器转变为具有自然语言界面的领域专家
- 🚀 简单的CLI界面：易于使用的分析和部署命令
- 📊 丰富的配置系统：使用系统提示和元数据生成全面的配置
- 🧪 生产就绪：完整的测试覆盖率、错误处理和TypeScript安全
- 🔌 符合MCP协议：适用于任何标准MCP服务器实现
安装
NPM包
# Install globally for CLI usage
npm install -g mcp-context-saver
# Or install locally in your project
npm install mcp-context-saver先决条件
- Node.js：18.0.0或更高版本
- npm：附带Node.js
- OpenAI API密钥：LLM功能所需
验证您的环境：
node --version # Should be v18.0.0 or higher
npm --version # Should be 6.0.0 or higher环境设置
所需环境变量：
# Set your OpenAI API key (required for both analysis and runtime)
export OPENAI_API_KEY=your-api-key-here备注：该系统使用OpenAI GPT-4o-mini进行分析和运行时协调。未来的版本将支持更多的LLM提供者。
与AI代理集成
克劳德桌面
要在Claude Desktop中使用MCP上下文保护程序，请将其添加到您的Claude配置中：
- 打开克劳德桌面配置：
macOS/Linux：
code ~/Library/Application\ Support/Claude/claude_desktop_config.json窗户：
code %APPDATA%\Claude\claude_desktop_config.json- 将MCP上下文保护程序添加到您的配置中：
{
"mcpServers": {
"mcp-context-saver": {
"command": "npx",
"args": [
"-y",
"mcp-context-saver",
"serve",
"/absolute/path/to/your/config.json"
],
"env": {
"OPENAI_API_KEY": "your-api-key-here"
}
}
}
}替换 /absolute/path/to/your/config.json 使用生成的配置文件的路径。
- 重新启动克劳德桌面 加载新配置。
- 验证连接 通过检查Claude Desktop中的MCP图标，它应该显示您的专家服务器。
克劳德代码（VS代码扩展）
Claude Code会自动发现MCP服务器。要添加MCP上下文保护程序，请执行以下操作：
- 生成包装器配置 对于您的目标MCP服务器：
mcp-context-saver analyze /path/to/your/mcp-server- 创建本地配置文件 在您的项目中：
mkdir .mcp
echo '{
"mcpServers": {
"expert-server": {
"command": "npx",
"args": [
"-y",
"mcp-context-saver",
"serve",
"./configs/your-server-config.json"
],
"env": {
"OPENAI_API_KEY": "'$OPENAI_API_KEY'"
}
}
}
}' > .mcp/config.json- 克劳德代码将自动 打开项目时检测并加载MCP服务器。
其他与MCP兼容的AI代理
MCP上下文保护程序适用于任何兼容MCP的客户端：
亚马逊Q（终端）
# Install Amazon Q CLI
brew install amazon-q
# Configure with MCP Context Saver
q configure mcp add mcp-context-saver \
--command "npx -y mcp-context-saver serve /path/to/config.json" \
--env OPENAI_API_KEY=$OPENAI_API_KEY自定义MCP客户端
对于自定义集成，请使用STDIO传输：
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const transport = new StdioClientTransport({
command: "npx",
args: ["-y", "mcp-context-saver", "serve", "./config.json"],
env: {
OPENAI_API_KEY: process.env.OPENAI_API_KEY
}
});
const client = new Client({
name: "my-client",
version: "1.0.0"
}, {
capabilities: {}
});
await client.connect(transport);快速开始
分析MCP服务器
分析任何MCP服务器以了解其功能：
mcp-context-saver analyze /path/to/your/mcp-server分析过程中会发生什么：
- 连接：建立到MCP服务器的STDIO传输
- 发现：询问服务器的所有功能（工具、资源、提示）
- LLM分析：使用OpenAI了解服务器的目的并生成专家身份
- 配置：使用系统提示和元数据创建全面的JSON配置
- 验证：确保配置有效并准备好运行时使用
运行包装服务器
使用生成的配置运行智能包装器：
mcp-context-saver serve ./configs/your-server-config.json包装服务器将您的MCP服务器转换为专家系统：
- 智能协调：LLM分析请求并自动选择适当的工具
- 自然语言接口：用户可以用简单的英语提出请求
- 三种操作模式：发现功能、执行任务或解释功能
- 多步骤操作：处理需要多个工具调用的复杂工作流
- 错误处理：优雅的故障恢复和信息丰富的错误消息
运作原理
1.分析阶段
flowchart TD
A[MCP Server] -->|STDIO| B[Analyzer]
B --> C[Discover Tools]
B --> D[Discover Resources]
B --> E[Discover Prompts]
C --> F[LLM Analysis]
D --> F
E --> F
F -->|OpenAI GPT-4o-mini| G[Expert Configuration]
G --> H[JSON Config File]分析仪：
- 连接到您的MCP服务器
- 发现所有可用的工具、资源和提示
- 使用LLM了解服务器的用途和功能
- 使用系统提示生成专门的专家配置
2.包装阶段
flowchart TD
A[User Query] -->|"Find all large files"| B[Expert Tool]
B --> C[Load Config]
C --> D[LLM Coordination]
D -->|"Use list_files + filter by size"| E[Wrapped MCP Server]
E --> F[Execute Tools]
F --> G[Return Results]
G --> H[Structured Response]包装：
- 向客户提供单一的专家工具
- 使用LLM协调来理解用户请求
- 自动选择并调用相应的底层工具
- 返回结构化结果
CLI参考
analyze 命令
分析MCP服务器并生成配置：
mcp-context-saver analyze [args...]论据：
- ``：MCP服务器可执行文件的路径
[args...]：传递给服务器的可选参数
示例：
# Analyze a JavaScript MCP server
mcp-context-saver analyze ./my-server.js
# Analyze a built Node.js server with arguments
mcp-context-saver analyze /usr/local/bin/mcp-server --config server.json
# Analyze a Python MCP server
mcp-context-saver analyze python my_mcp_server.py
# Analyze with complex arguments
mcp-context-saver analyze node server.js --port 3000 --verboseserve 命令
使用配置启动包装服务器：
mcp-context-saver serve 论据：
- `
：生成的配置文件的路径analyze`
例子：
mcp-context-saver serve ./configs/file-manager-1609459200000.json专家工具界面
包装器创建了一个支持三种操作模式的单一专家工具：
发现模式
了解专家可以做什么：
{
"name": "file-manager-expert",
"arguments": {
"query": "What can you help me with?",
"mode": "discover"
}
}退货：
- 能力概述
- 可用工具列表
- 可用资源和提示
执行模式（默认）
使用底层服务器执行任务：
{
"name": "file-manager-expert",
"arguments": {
"query": "List all files in the /home directory"
}
}LLM协调过程：
- 请求分析：了解用户的意图和要求
- 工具规划：确定需要哪些工具以及使用顺序
- 参数生成：为每个工具调用创建适当的参数
- 执行：调用底层MCP服务器工具
- 结果处理：结构和解释结果
解释模式
获取专家信息：
{
"name": "file-manager-expert",
"arguments": {
"query": "How do you work?",
"mode": "explain"
}
}退货：
- 专家描述
- 用于协调的系统提示
- 可用工具
- 使用说明
配置格式
生成的配置是全面的，包括所有必要的元数据：
{
"name": "File System Expert",
"description": "Comprehensive file and directory management with search capabilities",
"serverPath": "/path/to/your/mcp-server",
"args": ["--config", "server.json"],
"systemPrompt": "You are a File System Expert with comprehensive capabilities...\n\nWhen users request file operations:\n1. Use list_files to explore directories\n2. Use read_file to examine contents\n3. Always confirm destructive operations",
"capabilities": {
"tools": [
{
"name": "list_files",
"description": "List files and directories with filtering options",
"inputSchema": {
"type": "object",
"properties": {
"path": { "type": "string" },
"pattern": { "type": "string" }
}
}
}
],
"resources": [
{
"uri": "file://current-directory",
"name": "Current Directory Info"
}
],
"prompts": [
{
"name": "file-operation-template",
"description": "Template for file operations"
}
]
},
"metadata": {
"analyzedAt": "2023-12-07T10:30:00.000Z",
"toolCount": 8,
"resourceCount": 2,
"promptCount": 1
}
}发展
先决条件
- Node.js 18+
- OpenAI API密钥
地方发展设置
# Clone the repository
git clone https://github.com/your-org/mcp-context-saver.git
cd mcp-context-saver
# Install dependencies
npm install
# Set up environment
export OPENAI_API_KEY=your-api-key-here
# Build the project
npm run build
# Verify installation
npm test运行测试
# Run all tests
npm test
# Run unit tests only
npm run test:unit
# Run integration tests only
npm run test:integration开发命令
# Build TypeScript to JavaScript
npm run build
# Run CLI in development mode (with TypeScript)
npm run dev -- analyze ./simple-test-server.js
# Development with specific commands
npm run analyze -- ./test-server.js
npm run serve -- ./configs/test-config.json
# Clean build artifacts
npm run clean
# Watch mode for continuous building
npm run build -- --watch项目结构
mcp-context-saver/
├── src/ # Source TypeScript files
│ ├── analyzer.ts # Server analysis and config generation
│ ├── wrapper.ts # Runtime wrapper server
│ ├── cli.ts # Command-line interface
│ └── types.ts # Type definitions and Zod schemas
├── dist/ # Compiled JavaScript (gitignored)
├── tests/
│ ├── integration/
│ │ ├── full-flow.test.ts # End-to-end workflow tests
│ │ ├── mock-server.ts # TypeScript test server
│ │ └── mock-server.js # Simple JavaScript test server
│ └── unit/
│ ├── analyzer.test.ts # Analyzer component tests
│ └── wrapper.test.ts # Wrapper component tests
├── configs/ # Generated configurations (gitignored)
├── test-*-server/ # Test MCP servers for development
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── jest.config.js # Test configuration
├── ARCHITECTURE.md # System design documentation
├── CONTRIBUTING.md # Development guidelines
└── README.md # This file例子
示例：文件管理器服务器
# 1. Analyze a file manager MCP server
mcp-context-saver analyze ./file-manager-server.js
# Output:
# ✓ Analysis complete!
# Expert: File System Expert
# Description: Comprehensive file and directory management with search capabilities
#
# Capabilities discovered:
# - 8 tools
# - 2 resources
# - 1 prompts
#
# Configuration saved to: ./configs/file-system-expert-1609459200000.json
# 2. Start the wrapper server
mcp-context-saver serve ./configs/file-system-expert-1609459200000.json
# 3. Use from another MCP client
# The expert tool can now handle requests like:
# "Please find all .js files in the project directory and show me the largest ones"高级用法
智能系统提示生成
分析器使用OpenAI生成上下文系统提示，帮助LLM了解如何与每个特定的MCP服务器协调：
生成的系统提示示例：
You are a File System Expert with comprehensive file and directory management capabilities.
Your available tools allow you to:
- List and search files and directories (list_files)
- Read and write file contents (read_file, write_file)
- Create and delete files and directories (create_dir, delete_file)
- Search for files by patterns and content (search_files)
- Check file permissions and metadata (stat_file)
Coordination Guidelines:
1. For directory exploration, start with list_files
2. For file content tasks, use read_file before making changes
3. For search operations, use search_files with appropriate patterns
4. Always confirm destructive operations with users
5. Provide clear explanations of what you're doing
Error Handling:
- Check if paths exist before operations
- Handle permission errors gracefully
- Provide helpful error messages to users系统提示包括：
- 专家身份和能力概述
- 可用的工具描述和使用模式
- 工具协调的最佳实践
- 错误处理指南
- 用户交互原则
全面的错误处理
该系统提供详细的错误消息和可操作的指导：
环境问题：
Error: OPENAI_API_KEY environment variable is required
Please set your OpenAI API key:
export OPENAI_API_KEY=your-api-key
Get an API key at: https://platform.openai.com/api-keys服务器连接问题：
Error: Failed to connect to MCP server at ./my-server.js
Troubleshooting steps:
1. Verify the server path is correct
2. Ensure the server is executable (chmod +x)
3. Check if dependencies are installed (npm install)
4. Try running the server directly to test
For Node.js servers, you may need:
npm run build配置问题：
Error: Failed to load configuration from ./config.json
Possible causes:
1. File doesn't exist - check the path
2. Invalid JSON format - validate the file
3. Missing required fields - regenerate with analyze command
To create a new configuration:
mcp-context-saver analyze 运行时协调错误：
Error: Failed to coordinate with wrapped server
This usually means:
1. The wrapped server stopped responding
2. Invalid tool arguments were generated
3. OpenAI API quota exceeded
Check the wrapper server logs for more details.MCP集成故障排除
Claude桌面问题
服务器未出现在Claude中：
# Check Claude's MCP logs
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log # macOS/Linux
type "%APPDATA%\Claude\logs\mcp*.log" # Windows
# Common fixes:
# 1. Ensure absolute paths in configuration
# 2. Verify OPENAI_API_KEY is set in env section
# 3. Check that npx is installed globally: npm install -g npx
# 4. Restart Claude Desktop after config changes连接失败：
# Test the server manually
npx -y mcp-context-saver serve /path/to/config.json
# If this works, the issue is with Claude configuration
# If it fails, check:
# - Config file exists and is valid JSON
# - OPENAI_API_KEY is set correctly
# - The wrapped server path in config is correctClaude代码问题
未检测到MCP服务器：
# Ensure .mcp/config.json exists in project root
ls -la .mcp/config.json
# Validate JSON syntax
cat .mcp/config.json | jq .
# Reload VS Code window: Cmd/Ctrl + Shift + P → "Developer: Reload Window"通用MCP调试
启用调试日志记录：
# Run with debug output
DEBUG=* npx mcp-context-saver serve ./config.json 2>&1 | tee debug.log
# Check for:
# - Connection errors to wrapped server
# - OpenAI API errors
# - Tool execution failures验证包装服务器是否正常工作：
# Test the original MCP server directly
echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}' | node /path/to/original/server.js
# Should return server capabilities
# If not, fix the original server first常见环境问题：
# Windows: APPDATA not found
# Add to configuration:
"env": {
"OPENAI_API_KEY": "...",
"APPDATA": "C:\\Users\\YourUsername\\AppData\\Roaming\\"
}
# macOS/Linux: Permission denied
chmod +x /path/to/server.js贡献
我们欢迎捐款！请看 贡献.md 详细指南。
贡献者快速入门：
- 分叉和克隆 存储库
- 设置开发环境：
npm install
export OPENAI_API_KEY=your-key
npm run build
npm test- 创建要素分支：
git checkout -b feature/your-feature - 进行更改 遵循编码标准
- 添加综合测试 对于新功能
- 确保所有测试通过：
npm test - 更新文档 根据需要
- 提交拉取请求 描述清晰
开发资源：
许可证
MIT许可证-有关详细信息，请参阅许可证文件。
支持和资源
获取帮助：
- 📖 文档: 建筑.md 用于系统设计
- 🐛 错误报告:
- 💡 功能请求:
- 💬 讨论:
CLI帮助：
# General help
mcp-context-saver --help
# Command-specific help
mcp-context-saver analyze --help
mcp-context-saver serve --help示例项目：
- 集成测试显示真实的使用模式
- 测试服务器演示MCP实现
- 生成的配置显示预期的输出格式
相关资源：