Project Context MCP server

project-context

project-context is a local, provider-neutral MCP server for repository-scoped issue handling. It gives agents one guarded interface to Linear, GitHub Issues, GitHub Projects v2, and Jira Cloud while keeping project mappings and credentials outside source repositories.

The server resolves the current Git repository, selects its configured issue provider, verifies the authenticated account, and separates every write into a preview and a single-attempt apply step. Pull requests, releases, repository administration, Git authentication, and commit signing are intentionally out of scope.

Quick start

Requirements: Node.js 22 or newer on Linux or macOS.

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

The first command creates secure, host-local starter files without overwriting anything that already exists:

~/.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/

Copy and adapt the sanitized examples in examples/, validate the result, and then register the project-context-mcp stdio command in your MCP client. The complete Codex, Claude, Zed, and VS Code configurations are in docs/installation.md.

Safety model

identity. Missing or ambiguous context fails closed for writes.

• Host-local YAML determines the repository, provider, target, and expected

argv-only commands. Literal secrets in YAML are rejected.

• Credentials resolve from files, environment variables, OS keychains, or

response sizes and timeouts, and never automatically retry writes.

• Provider calls are restricted to fixed HTTPS origins, reject redirects, cap

project-context never proxies the upstream server's broader tool catalog.

• Linear issue operations use a fixed allowlist of Linear's hosted MCP tools;

and can be claimed only once. An uncertain apply result becomes indeterminate and is never replayed automatically.

• Prepared writes expire after ten minutes, are encrypted with AES-256-GCM,

locally. The project has no telemetry.

• Mutation audit records contain metadata only, are mode 0600, and rotate

Read docs/threat-model.md for trust boundaries and residual risks, and docs/routing-and-safety.md for operational behavior.

Commands and MCP tools

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

The stdio server exposes eleven tools:

• resolveprojectcontext
• list_issues
• search_issues
• list_users
• search_users
• searchissueoptions
• getissuecapabilities
• get_issue
• listissuecomments
• prepareissuechange
• applyissuechange

Every tool has an input and output schema. Starting the server has no setup side effects; when host configuration is absent, tools return an actionable structured error.

Shortened. The full README is on GitHub.