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

• Host-local YAML determines the repository, provider, target, and expected identity. Missing or ambiguous context fails closed for writes.
• Credentials resolve from files, environment variables, OS keychains, or argv-only commands. Literal secrets in YAML are rejected.
• Provider calls are restricted to fixed HTTPS origins, reject redirects, cap response sizes and timeouts, and never automatically retry writes.
• Linear issue operations use a fixed allowlist of Linear's hosted MCP tools; project-context never proxies the upstream server's broader tool catalog.
• Prepared writes expire after ten minutes, are encrypted with AES-256-GCM, and can be claimed only once. An uncertain apply result becomes indeterminate and is never replayed automatically.
• Mutation audit records contain metadata only, are mode 0600, and rotate locally. The project has no telemetry.

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:

• 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

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.

Linear additionally supports target-scoped subissues, due dates, estimates, cycles, milestones, blocking/related/duplicate relationships, comment replies and edits, archived listing, and relation-expanded reads. SLA fields, permanent deletion, and non-issue Linear features are not exposed.

GitHub additionally supports repository issue types and milestones, native parent/subissue hierarchies, blocking dependencies, duplicate relationships, comment edits, direct-subissue listing, and relation-expanded reads. GitHub custom-field mappings, generic related-to relationships, threaded comment replies, pull requests, and repository administration are not exposed.

integration manifest prints the provider-neutral command definition by default. Pass --client codex, claude, zed, or vscode to emit native, ready-to-paste configuration pinned to the installed package version. Add --json when automation needs an envelope containing the client, format, and configuration.

The optional project-issues agent skill is packaged but never installed as an npm lifecycle side effect:

project-context skill status
project-context skill install

Use --replace only after reviewing status; replacement creates a timestamped backup.

Documentation

• docs/installation.md: package and MCP client setup.
• docs/configuration.md: host-local YAML and credential resolvers.
• docs/architecture.md: components and runtime boundaries.
• docs/provider-behavior.md: provider-specific behavior.
• docs/releasing.md: bootstrap, semantic release, npm, and MCP Registry.
• CONTRIBUTING.md: development and review requirements.
• SECURITY.md: supported versions and private reporting.

License and attribution

This project is available under the MIT License, copyright 2026 Richard Sandoval. The copyright and permission notice must remain with copies or substantial portions of the software.

If this repository is used as the starting point for another project, a visible acknowledgment is appreciated:

Based on project-context, created by Richard Sandoval.