contextualizer

上下文化器MCP服务器

一个用于AI优化的项目设置和管理的MCP（模型上下文协议）服务器。它使Claude能够通过上下文监控、Git钩子和内存管理来设置和管理开发项目。

状态

当前阶段Epic 1 完整版 - 配备 CI/CD 的完整 MCP 服务器

具备全面工具套件、资源提供者、快速提示模板和自动化CI/CD流水线的生产就绪MCP服务器。

要求

• Node.js 18及以上版本
• npm 或 yarn

安装

从NPM（发布时）

npm install -g contextualizer

来自源（或“来源”）

git clone https://github.com/yourusername/contextualizer.git
cd contextualizer
npm install
npm run build

发展

构建

npm run build

构建TypeScript项目以 dist/ 使用tsup。

开发模式

npm run dev

自动监控更改并重建。

运行服务器

npm start

启动带有stdio传输的MCP服务器。

测试

运行测试

npm test

观察模式

npm run test:watch

覆盖率报告

npm run test:coverage

当前覆盖率：100%（所有可测试代码）

类型检查

npm run typecheck

建筑

项目结构

contextualizer/
├── src/
│   ├── server.ts           # Main MCP server entry point
│   ├── types/
│   │   └── mcp.ts          # MCP type definitions
│   ├── tools/
│   │   └── index.ts        # Tool registry (empty - Story 1.2+)
│   ├── resources/
│   │   └── index.ts        # Resource registry (empty - Story 1.2+)
│   ├── prompts/
│   │   └── index.ts        # Prompt registry (empty - Story 1.2+)
│   └── utils/
│       └── logger.ts       # Pino logger wrapper
├── tests/
│   ├── unit/               # Unit tests
│   └── integration/        # Integration tests
├── dist/                   # Build output
└── package.json

MCP协议

服务器通过stdio传输实现了模型上下文协议：

• 交流通过标准输入/输出进行的JSON-RPC 2.0
• 能力工具、资源、提示
• 交通StdioServerTransport 翻译为中文是：“标准I/O服务器传输（或：标准输入输出服务器传输）”

服务器生命周期

1. 使用元数据和功能初始化服务器
2. 注册请求处理程序（工具、资源、提示）
3. 启动标准I/O传输
4. 优雅地处理关闭操作（SIGINT/SIGTERM）

记录日志

使用 pino 进行结构化日志记录：

• 日志文件： .contextualizer/mcp.log
• 格式带有时间戳的JSON
• 等级错误，警告，信息，调试

MCP服务器配置

要在Claude Desktop中使用此服务器，请在您的Claude配置中添加：

{
  "mcpServers": {
    "contextualizer": {
      "command": "node",
      "args": ["/path/to/contextualizer/dist/server.js"]
    }
  }
}

特点/功能

MCP 工具（故事 1.2）✅

• 初始化项目使用 Git、钩子和上下文监控初始化新项目
• 跑医生（或“急救医生”）全面的项目健康诊断
• 读取上下文阅读 .contextualizer/context.json 配置
• 更新上下文修改上下文监控设置
• 安装钩子为开发工作流设置Git钩子
• 卸载钩子干净地移除 Git 钩子

MCP资源公司（故事1.3）✅

• 配置当前项目配置和设置
• 诊断（技术/方法）实时项目健康状况诊断
• 预设可用的项目模板和预设

MCP 提示（故事 1.4）✅

• 设置向导交互式项目设置向导
• 健康检查项目健康分析及建议

文档（故事1.5）✅

• 建筑指南系统设计和组件规格
• 用户指南最终用户文档和工作流程
• 开发者指南贡献与开发指南
• API 文档完整的MCP协议实现

测试基础设施（故事1.6）✅

• 555 测试全面的测试套件（481个单元测试 + 74个集成测试）
• 100%覆盖率所有可测试的代码路径均已验证
• 集成测试完整的MCP协议及工具验证
• 性能测试非功能需求（NFR）合规性验证

CI/CD 管道（故事 1.7）✅

• GitHub Actions CI（持续集成）在节点18、20、22上进行矩阵测试
• 自动化出版带有来源信息的NPM发布版本
• 代码覆盖率Codecov 集成
• 发布自动化生成变更日志和发布GitHub版本

演出

从NFR1到NFR4的性能目标：

• ✅ 服务器启动时间：\< 500毫秒
• ✅ MCP握手时间：\< 200毫秒
• ✅ 日志记录开销：\< 5毫秒

测试

测试覆盖率

• 线条100%
• 功能百分之百
• 分支100%
• 陈述；声明100%

注： server.ts 由于该部分已通过集成测试（作为独立进程启动）进行了全面测试，因此不包含在单元测试覆盖率中。

测试文件

• tests/unit/types.test.ts - 类型定义
• tests/unit/registries.test.ts - 工具/资源/提示注册表
• tests/unit/logger.test.ts - 日志记录功能
• tests/unit/server.test.ts - 服务器配置
• tests/integration/mcp-protocol.test.ts - 完整的MCP协议

贡献

这个项目遵循BMAD（构建-测量-分析-部署）的工作流程：

1. 阅读故事要求 docs/stories/
2. 遵循架构规范 docs/architecture/
3. 实施并进行测试（单元测试+集成测试）
4. 确保代码覆盖率80%以上
5. 更新文档

许可证

麻省理工学院（MIT）