MCP Context Manager

MCP Context Manager

一组 Model Context Protocol（MCP）服务，可在整个项目生命周期的不同工作阶段，为 AI 模型提供持久上下文。

每个项目的上下文都存储在由相应领域的服务管理的领域专属知识图谱中。所有领域服务都可以通过提供统一访问入口的中央 Context Manager 进行管理。

每个领域服务也都是独立的 MCP Server，无需 Context Manager 即可单独使用。

功能

• 持久上下文：从构思到生产／发布／完成，随时轻松使用 buildcontext、loadcontext 和 deletecontext
• 高效访问：让 AI 模型在需要时获取所需的准确上下文
• 会话管理：
  1. 使用 startsession 工具，概览你在以往会话中的工作
  2. 使用 endsession 工具，分析整个会话并更新知识图谱，供后续会话使用
• 跨领域支持：通过单一接口使用多个知识领域，包括建立不同领域实体之间的关系

为什么使用知识图谱？

释放上下文窗口空间（提升性能），并最大限度地降低 Token 成本（提高效率）。

可用服务

contextmanager 可协调多个领域专属 MCP 服务：

1. Developer MCP Server：软件开发上下文，包含项目、组件和任务等实体。支持状态跟踪（未激活、进行中、已完成）、优先级管理（高、低），以及通过 precedes 关系安排任务顺序。

2. Project MCP Server：项目管理上下文，包含项目、任务和资源等实体。支持状态管理（未激活、进行中、已完成）、优先级分配（高、低）和任务排序。

3. Student MCP Server：教育上下文，包含课程、作业和考试等实体。支持状态跟踪（进行中、已完成、待处理、已放弃）、作业优先级管理（高、低）和学习顺序安排。

4. Qualitative Research MCP Server：定性研究上下文，包含研究、参与者和访谈等实体。支持研究活动状态跟踪（进行中、已完成、待处理、已放弃）、优先级管理（高、低）和分析顺序安排。

5. Quantitative Research MCP Server：定量研究上下文，包含数据集、变量和分析等实体。支持状态管理（进行中、已完成、待处理、已放弃）、优先级分配（高、低）和流程顺序管理。

有关各领域服务的详细文档，请参阅相应目录中的 README 文件：

• Developer 服务
• Project 服务
• Student 服务
• Qualitative Research 服务
• Quantitative Research 服务

Context Manager 的优势

Context Manager 提供：

• 统一接口：通过单一接口访问所有领域服务。
• 智能路由：自动将请求路由到相应的领域服务。
• 跨领域上下文：维护不同领域之间的关联。
• 一致的状态管理：在各领域采用标准化的状态跟踪方式。
• 统一的优先级系统：在不同上下文中采用一致的优先级管理方式。
• 集成排序：在不同领域的工作流中采用协调一致的顺序安排方式。

实现

Context Manager 使用 MCP Client SDK 与领域专属 MCP 服务通信。它：

1. 维护领域服务注册表及其连接信息
2. 创建 MCP 客户端以连接各领域服务
3. 根据当前活动领域，将请求路由到相应的领域服务
4. 提供跨领域功能，以关联不同领域中的实体
5. 确保对状态、优先级和顺序关系进行一致处理

路径解析

Context Manager 会在运行时构造绝对路径，以定位领域服务。如果需要修改领域服务的路径，请更新 main/index.ts 中的 domains 数组。

安装与使用

你可以通过多种方式使用 MCP Context Manager：

使用 npx（推荐）

直接通过 npx 运行：

npx github:tejpalvirk/contextmanager

全局安装

全局安装，使所有服务都可作为命令使用：

npm install -g github:tejpalvirk/contextmanager

然后运行：

mcp-server-contextmanager

或者直接运行特定的领域服务：

contextmanager-developer
contextmanager-project
contextmanager-student
contextmanager-qualitativeresearch
contextmanager-quantitativeresearch

克隆并从源代码构建

用于开发或自定义：

git clone https://github.com/tejpalvirk/contextmanager.git
cd contextmanager
npm install
npm run build

然后运行：

node main/index.js

命令行参数

Context Manager 和领域服务接受以下命令行参数：

# Run on a specific port (default: 3000)
npx github:tejpalvirk/contextmanager --port 3001

# Enable debug logging
npx github:tejpalvirk/contextmanager --debug

# Specify a config file
npx github:tejpalvirk/contextmanager --config ./my-config.json

# Run only specific domain servers
npx github:tejpalvirk/contextmanager --domains developer,project

环境变量

每个领域服务都支持以下环境变量，用于自定义数据的存储位置：

• MEMORY_FILE_PATH：存储知识图谱数据的路径

  • 可以是绝对路径或相对路径（相对路径以当前工作目录为基准）
  • 默认值：<domain_directory>/memory.json

• SESSIONS_FILE_PATH：存储会话数据的路径

  • 可以是绝对路径或相对路径（相对路径以当前工作目录为基准）
  • 默认值：<domain_directory>/sessions.json

示例用法：

# Store data in the current directory
MEMORY_FILE_PATH="./my-dev-memory.json" SESSIONS_FILE_PATH="./my-dev-sessions.json" npx github:tejpalvirk/contextmanager

# Store data in a specific location (absolute path)
MEMORY_FILE_PATH="/path/to/data/developer-memory.json" npx github:tejpalvirk/contextmanager

# Store data in user's home directory
MEMORY_FILE_PATH="$HOME/contextmanager/memory.json" npx github:tejpalvirk/contextmanager

与领域服务交互

领域管理

使用 setActiveDomain 工具选择要使用的领域：

setActiveDomain(domain="developer")

会话管理

为当前活动领域启动新会话：

startsession(domain="developer")

完成后结束会话：

endsession(sessionId="session_id_here", stage="assembly", stageNumber=6, totalStages=6, nextStageNeeded=false)

上下文操作

为当前活动领域构建上下文：

buildcontext(type="entities", data={...})

加载特定实体的上下文：

loadcontext(entityName="MyProject", entityType="project")

删除上下文：

deletecontext(type="entities", data={...})

实体状态与优先级管理

为实体分配状态：

buildcontext(type="relations", data=[
  { from: "LoginFeature", to: "active", relationType: "has_status" }
])

设置实体优先级：

buildcontext(type="relations", data=[
  { from: "BugFix", to: "high", relationType: "has_priority" }
])

定义顺序关系：

buildcontext(type="relations", data=[
  { from: "DataModel", to: "UserInterface", relationType: "precedes" }
])

示例：使用 Developer 领域

// Set the active domain to developer
setActiveDomain(domain="developer")

// Start a new session
startsession(domain="developer")

// Create a new project entity
buildcontext(type="entities", data={
  "entityType": "project",
  "name": "MyProject",
  "description": "A sample project",
  "language": "TypeScript",
  "framework": "React"
})

// Load context for the project
loadcontext(entityName="MyProject", entityType="project")

// Create a component for the project and set its status to active
buildcontext(type="entities", data={
  "entityType": "component",
  "name": "AuthService",
  "project": "MyProject",
  "description": "Authentication service component",
  "dependencies": ["UserService"]
})

buildcontext(type="relations", data=[
  { from: "AuthService", to: "active", relationType: "has_status" },
  { from: "AuthService", to: "high", relationType: "has_priority" }
])

跨领域操作

在不同领域的实体之间创建关系：

relateCrossDomain(fromDomain="developer", fromEntity="ProjectX", toDomain="project", toEntity="ProjectX", relationType="manages")

示例：跨领域集成

// Create relationship between developer project and project management task
relateCrossDomain(
  fromDomain="developer", 
  fromEntity="MyProject", 
  toDomain="project", 
  toEntity="ProjectX", 
  relationType="manages"
)

与 Claude 集成

在 Claude Desktop 中，于设置里配置 Context Manager：

{
  "mcpServers": {
    "contextmanager": {
      "command": "npx",
      "args": [
        "-y",
        "github:tejpalvirk/contextmanager"
      ],
      "options": {
        "port": 3000,
        "domains": ["developer", "project", "student"]
      }
    }
  }
}

故障排除

常见问题

1. 端口已被占用：

   Error: listen EADDRINUSE: address already in use :::3000
   

   解决方案：使用 --port 选项指定其他端口。

2. 连接被拒绝：

   Error: connect ECONNREFUSED 127.0.0.1:3000
   

   解决方案：确保服务正在运行，并且可通过指定地址访问。

3. 找不到领域服务：

   Error: Domain server 'developer' not found
   

   解决方案：检查领域名称是否正确，以及该服务是否已在 Context Manager 中注册。

4. 路径解析错误：

   Error: Cannot find module '...'
   

   解决方案：确保 main/index.ts 中 domains 数组里的所有路径都已正确指定。

5. 找不到方法：

   Error: Method 'buildcontext' not found in domain 'developer'
   

   解决方案：确认方法名称，并确保领域服务支持该方法。

6. 状态或优先级值无效：

   Error: Invalid status value 'in_progress'. Valid values are: inactive, active, complete
   

   解决方案：确保使用了该特定领域对应的正确状态值。

后续步骤

• 用 YAML 替换 JSON，以将令牌效率提升 20-30%
• 探索 Markdown 中的知识图谱

版本管理

此软件包遵循语义化版本：

• MAJOR：不兼容的 API 变更
• MINOR：向后兼容的功能新增
• PATCH：向后兼容的错误修复

当前版本：1.0.0

贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

编码规范

• 所有新代码均使用 TypeScript
• 遵循现有代码风格
• 为新功能添加测试
• 按需更新文档

开发

先决条件

• Node.js v16 或更高版本
• npm v7 或更高版本

构建

npm install
npm run build

测试

npm test

许可证

MIT

致谢

本项目基于 Anthropic 为 Claude 创建的 Model Context Protocol 构建。