AI导哈

项目上下文服务器

一个模型上下文协议（MCP）服务器，用于在Claude Code会话之间提供持久的项目上下文和规划状态，消除每次开始新会话时重新解释项目细节的需要。

  • by aaronfeingold
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 aaronfeingold/mcp-project-context

使用说明

MCP项目上下文服务器

一种模型上下文协议（MCP）服务器，在克劳德代码会话之间提供持久的项目上下文和计划状态。这消除了每次开始新的编码会话时重新解释项目细节、当前状态和开发上下文的需要。

它做什么

MCP项目上下文服务器充当开发项目的持久内存层，维护：

  • 项目信息：名称、描述、当前阶段和状态
  • 技术栈：前端、后端、数据库、基础设施和工具选择
  • 任务管理：具有优先级、状态跟踪和依赖关系的开发任务
  • 决策历史：具有推理能力的架构和技术决策
  • 会话连续性：往届会议的目标、成就和阻碍因素
  • 开发说明：重要观察和见解

运作原理

服务器实现了模型上下文协议，为Claude Code提供了管理项目上下文的工具：

  1. 项目创建：使用技术栈和当前阶段初始化新项目
  2. 上下文检索：获取全面的项目状态和历史
  3. 任务管理：创建、更新和跟踪开发任务
  4. 决策记录：记录重要的技术和架构决策
  5. 会话跟踪：保持发展会议之间的连续性
  6. 记笔记：捕捉重要见解和观察结果

数据以JSON文件的形式存储在本地 data 目录，使备份、版本控制或手动检查变得容易。

主要特点

  • 持久上下文：项目状态在Claude Code会话之间保留
  • 技术栈意识：跟踪您喜欢的技术和工具
  • 任务优先级：按优先级和状态跟踪组织工作
  • 决策文件：维护架构决策记录（ADR）
  • 会议目标：跟踪你的计划与成就
  • 基于文件的存储：简单的JSON存储，易于理解和备份

先决条件

  • Node.js 18或更高版本
  • pnpm包管理器
  • Claude Code命令行界面工具

安装

  1. 克隆并设置项目：
git clone <repository-url>
cd mcp-project-context
pnpm install
  1. 构建服务器：
pnpm run build
  1. 使服务器可执行：
chmod +x dist/index.js

配置

Claude代码设置

  1. 创建或编辑Claude Code MCP配置文件：
mkdir -p ~/.claude
  1. 将您的服务器配置添加到`~/.claude.json：
{
    "mcpServers": {
      "mcp-project-context": {
        "type": "stdio",
        "command": "/path/to/mcp-project-context/dist/index.js",
        "args": [],
        "env": {}
      }
    }
}

替换 /absolute/path/to/your/mcp-project-context 带有项目目录的实际路径。

  1. 验证配置：
cat ~/.claude/mcp.json

用法

配置后，Claude Code将自动启动并连接到您的MCP服务器。然后，您可以使用自然语言与项目上下文进行交互：

示例命令

创建新项目：

"Create a new project called 'E-commerce Platform' for building a modern online store using Next.js, Node.js, PostgreSQL, and Docker"

获取当前项目状态：

"What's the current status of my project? Where did we leave off?"

添加开发任务：

"Add a high-priority task to implement user authentication with OAuth"

记录架构决策：

"Record that we decided to use Prisma as our ORM because it provides better TypeScript support and easier migrations"

更新任务状态：

"Mark the authentication task as completed"

添加项目注释：

"Add a note that the API rate limiting is causing issues in development"

可用工具

服务器为Claude Code提供了以下工具：

  • create_project -使用技术栈和描述初始化新项目
  • get_project_context -检索全面的项目状态和历史记录
  • list_projects -显示按上次访问顺序排列的所有项目
  • add_task -创建具有优先级的新开发任务
  • update_task -修改任务状态、优先级或详细信息
  • add_note -捕捉重要的观察和见解
  • record_decision -记录架构和技术决策
  • start_session -以具体目标开始开发会议

数据存储

项目数据存储在 data 目录：

data/
├── projects/
│   ├── project-uuid-1.json
│   ├── project-uuid-2.json
│   └── project-uuid-3.json
└── sessions/
    ├── session-uuid-1.json
    ├── session-uuid-2.json
    └── session-uuid-3.json

每个文件都包含结构化的JSON数据，您可以根据需要进行检查或备份。

发展

项目结构

mcp-project-context/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server implementation
│   ├── storage/
│   │   ├── project-store.ts  # File-based storage layer
│   │   └── context-manager.ts # Context management logic
│   └── types/
│       └── project-types.ts  # TypeScript type definitions
├── data/                     # Project data storage
├── package.json
├── tsconfig.json
└── README.md

可用脚本

  • pnpm run build -将TypeScript编译为JavaScript
  • pnpm run start -运行已编译的服务器
  • pnpm run dev -在开发模式下运行并自动重新加载

测试服务器

您可以手动测试服务器：

# Start the server directly
node dist/index.js

# The server will wait for MCP protocol messages via stdin

对于交互式测试，请使用MCP检查器：

npx @modelcontextprotocol/inspector node dist/index.js

故障排除

服务器连接问题

  1. 验证服务器构建是否成功：
pnpm run build
  1. 检查可执行位是否已设置：
ls -la dist/index.js
chmod +x dist/index.js
  1. 手动测试服务器：
node dist/index.js
  1. 验证克劳德代码配置：
cat ~/.claude/mcp.json

数据目录问题

如果遇到权限错误，请确保数据目录存在并且可写：

mkdir -p data/projects data/sessions
chmod -R 755 data/

克劳德代码日志

检查Claude代码日志是否存在连接问题：

# The server logs errors to stderr, which Claude Code captures
# Check your terminal output when starting Claude Code

隐私和数据

  • 所有项目数据都存储在本地计算机上
  • 没有数据传输到外部服务
  • JSON文件可以轻松备份或版本控制
  • 每个开发人员/机器维护单独的项目上下文

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

关于以下问题：

相关 MCP