Project Context

What Project Context does

Project Context MCP server routes repository-scoped issue operations to the provider configured for the current Git repository. Supported systems are Linear, GitHub Issues, GitHub Projects v2, and Jira Cloud. Repository mappings, credentials, templates, prepared changes, and audit state live in host-local paths rather than in the source repository.

The server checks the repository context and authenticated identity before provider operations. If configuration is missing or ambiguous, tools return a structured error and writes fail closed. The interface is provider-neutral, while provider-specific capabilities remain limited to the operations exposed by the project.

How it works

The stdio process resolves the working repository, reads its host-local project configuration, and selects the matching issue provider and target. Credentials can come from files, environment variables, operating-system keychains, or commands that return values through arguments. Literal secrets in YAML are rejected.

Changes are split into preparation and application. A prepared change is encrypted with AES-256-GCM, expires after ten minutes, and can be claimed once. The server does not automatically retry writes; if the outcome cannot be determined, it reports an indeterminate result rather than replaying the operation. Provider requests use fixed HTTPS origins, reject redirects, enforce response and timeout limits, and do not automatically retry mutations.

Setup and configuration

Project Context MCP server requires Node.js 22 or newer on Linux or macOS. Run the package's setup command to create starter files under ~/.agents/config/project-context/, including projects.yaml, credentials.yaml, templates, and secrets directories. It also creates local state under ~/.local/state/project-context/ without overwriting existing files.

Adapt the sanitized examples, then run configuration validation and the diagnostic command before registering the project-context-mcp stdio command in an MCP client. The repository provides native configuration generation for Codex, Claude, Zed, and VS Code through the integration manifest command. The optional project-issues skill is installed separately and is not added as an npm lifecycle side effect.

Tools and capabilities

The Project Context MCP server exposes these tools:

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

Read operations cover issue, user, comment, option, capability, and repository-context lookup. Linear-specific support includes subissues, due dates, estimates, cycles, milestones, selected relationships, comment replies and edits, archived issue listing, and relation-expanded reads. GitHub-specific support includes issue types, milestones, parent/subissue hierarchies, blocking and duplicate relationships, comment edits, direct-subissue listing, and relation-expanded reads.

Limitations and notes

The project does not expose pull-request operations, releases, repository administration, Git authentication, commit signing, or non-issue Linear features. Linear SLA fields and permanent deletion are unavailable. GitHub custom-field mappings, generic related-to relationships, threaded comment replies, pull requests, and repository administration are also outside the exposed interface.

Mutation audit records contain metadata only, use restrictive local file permissions, and rotate locally. The project reports no telemetry. Starting the server itself does not perform setup; absent host configuration produces an actionable structured error instead.