Project Context

project-context

project-context 是一个本地、与提供商无关的 MCP 服务，用于处理特定于代码仓库的问题。它为 Agent 提供统一且受保护的接口，用于访问 Linear、GitHub Issues、GitHub Projects v2 和 Jira Cloud，同时将项目映射和凭据保存在源代码仓库之外。

该服务会解析当前 Git 仓库，选择已配置的问题跟踪提供商，验证经过身份验证的账户，并将每次写入操作分为预览和仅尝试一次的应用步骤。拉取请求、发布、仓库管理、Git 身份验证和提交签名均不在支持范围内。

快速开始

要求：在 Linux 或 macOS 上使用 Node.js 22 或更高版本。

VERSION=0.1.0
npx -y --package="@sandovalrr/project-context-mcp@$VERSION" project-context setup
npx -y --package="@sandovalrr/project-context-mcp@$VERSION" project-context doctor

第一条命令会创建仅限当前主机访问的安全初始文件，不会覆盖任何已存在的文件：

~/.agents/config/project-context/projects.yaml
~/.agents/config/project-context/credentials.yaml
~/.agents/config/project-context/templates/
~/.agents/config/project-context/secrets/
~/.local/state/project-context/

复制并调整 examples/ 中经过清理的示例，验证结果，然后在你的 MCP 客户端中注册 project-context-mcp stdio 命令。Codex、Claude、Zed 和 VS Code 的完整配置位于 docs/installation.md。

安全模型

• 仅限主机的 YAML 配置用于确定代码仓库、提供商、目标和预期身份。缺失或不明确的上下文会导致写入操作失败关闭。
• 凭据从文件、环境变量、操作系统密钥链或仅通过 argv 传递的命令中获取。YAML 中不允许出现明文机密。
• 提供商调用仅限固定的 HTTPS 来源，会拒绝重定向、限制响应大小和超时时间，并且绝不会自动重试写入操作。
• Linear 问题操作使用 Linear 托管 MCP 工具的固定允许列表；project-context 绝不会代理上游服务范围更广的工具目录。
• 已准备的写入操作在十分钟后过期，使用 AES-256-GCM 加密，并且只能领取一次。应用结果不确定时会标记为 indeterminate，且绝不会自动重放。
• 修改审计记录仅包含元数据，文件权限为 0600，并在本地轮换。此项目不收集遥测数据。

请阅读 docs/threat-model.md，了解信任边界和剩余风险；阅读 docs/routing-and-safety.md，了解运行行为。

命令和 MCP 工具

project-context --help
project-context setup --guided
project-context config validate
project-context resolve --cwd /path/to/repository
project-context issue list --status open --status in_progress
project-context issue list --parent linear:ENG-42
project-context issue user search "John Smith"
project-context issue capabilities
project-context issue option search labels security
project-context issue option search cycle current
project-context issue get linear:ENG-42 --include-relations
project-context issue comment list github:#42 --limit 20
project-context issue prepare create --title "Child task" --parent ENG-42
project-context doctor
project-context audit list
project-context skill status
project-context integration manifest --client codex

stdio 服务公开了十一个工具：

• resolve_project_context
• list_issues
• search_issues
• list_users
• search_users
• search_issue_options
• get_issue_capabilities
• get_issue
• list_issue_comments
• prepare_issue_change
• apply_issue_change

每个工具都有输入和输出架构。启动服务不会产生设置方面的副作用；如果缺少主机配置，工具会返回可执行操作的结构化错误。

Linear 还支持限定目标范围的子问题、截止日期、估算值、周期、里程碑、阻塞／相关／重复关系、评论回复和编辑、已归档问题列表，以及展开关系的读取。不会公开 SLA 字段、永久删除和非问题类 Linear 功能。

GitHub 还支持仓库问题类型和里程碑、原生父子问题层级、阻塞依赖项、重复关系、评论编辑、直接子问题列表，以及展开关系的读取。不会公开 GitHub 自定义字段映射、通用相关关系、串接式评论回复、拉取请求和仓库管理功能。

默认情况下，integration manifest 会打印与提供商无关的命令定义。传入 --client codex、claude、zed 或 vscode，即可输出固定到已安装软件包版本的原生可粘贴配置。自动化需要包含客户端、格式和配置的封装对象时，可添加 --json。

可选的 project-issues Agent 技能已打包，但绝不会作为 npm 生命周期副作用自动安装：

project-context skill status
project-context skill install

只有在查看状态后才使用 --replace；替换操作会创建带时间戳的备份。

文档

• docs/installation.md：软件包和 MCP 客户端设置。
• docs/configuration.md：主机本地 YAML 和凭据解析器。
• docs/architecture.md：组件和运行时边界。
• docs/provider-behavior.md：特定提供方的行为。
• docs/releasing.md：引导、语义化发布、npm 和 MCP Registry。
• CONTRIBUTING.md：开发和评审要求。
• SECURITY.md：受支持的版本和私下报告方式。

许可证和致谢

本项目采用 MIT 许可证，版权所有 2026 Richard Sandoval。软件副本或实质性部分必须保留版权和许可声明。

如果将本仓库用作另一个项目的起点，欢迎在显眼处注明：

基于 project-context，由 Richard Sandoval 创建。