MCP & Agent Integration#

What is the MCP Package#

@jsonbored/gittensory-mcp is the first-class agent surface of the Gittensory platform — a published npm package that gives AI agents and miners structured, privacy-preserving access to Gittensory's intelligence layer 1. It is one of four independent deployment surfaces alongside the Worker API, the frontend, and the GitHub App 2.

The package is a local stdio MCP wrapper: it reads git metadata directly from your machine, then calls the Gittensory Worker API at https://gittensory-api.aethereal.dev with metadata-only payloads to return scored, actionable intelligence. Source code is never uploaded 3.

What is the Model Context Protocol?#

The Model Context Protocol (MCP) is a standardized interface that allows coding agents and AI tools to connect with external data sources and services in a structured, tool-call-based way. Rather than ad-hoc API integrations, MCP defines a common schema for tool registration, input validation, and structured JSON responses — enabling any MCP-compatible client (Claude Desktop, Cursor, Codex, etc.) to interact with a server like Gittensory without custom wiring.

@jsonbored/gittensory-mcp implements MCP using @modelcontextprotocol/sdk v1.26.0 4. It registers 21 tools across five capability areas and exposes them over standard stdio transport, making Gittensory's intelligence layer accessible to any MCP-compatible client.

What it provides#

The package exposes two surfaces for different audiences:

• 21 MCP tools — structured tool definitions callable by AI agents via the MCP protocol, covering repo intelligence, PR preflight, scoring, contributor decisions, current-branch analysis, and agent planning 5
• 13 CLI commands — human-friendly equivalents of the same capabilities, usable directly from a terminal or CI script

It is designed for three audiences:

• Miners — use the package to plan work, preflight branches before opening PRs, and prepare public-safe PR packets
• Coding agents — consume deterministic tool schemas to gain structured Gittensor context without requiring source code upload
• Maintainers — access private reviewability context and contributor decision packs through the API

The architecture follows a strict deterministic and auditable design: core decisions are rule-based, not AI-generated, and the package never edits code, opens PRs, posts comments, closes, merges, or labels without an explicit user- or maintainer-triggered flow 6.

Installation & Authentication#

Installing the package#

Install @jsonbored/gittensory-mcp globally from npm. The package requires Node.js 22.0.0 or higher 7.

npm install -g @jsonbored/gittensory-mcp

If you are working from a local checkout of the Gittensory monorepo, use the workspace link instead:

npm install
npm link --workspace @jsonbored/gittensory-mcp

Logging in#

After installation, authenticate with the Gittensory API:

gittensory-mcp login

This uses GitHub Device Flow by default. The command prints a verification URI and a short user code; open the URL in your browser, enter the code, and approve the OAuth prompt. The wrapper polls for the token and stores a Gittensory session token (not a GitHub token) in your local config file 8.

For non-interactive environments — CI, agent-hosted setups, or bootstrap from an existing GitHub token:

gittensory-mcp login --github-token "$(gh auth token)"

The session token is persisted at ~/.config/gittensory/config.json by default. You can override the location with GITTENSORY_CONFIG_PATH or GITTENSORY_CONFIG_DIR 9.

Token resolution order#

The package resolves the API token in the following priority order 10:

1. GITTENSORY_API_TOKEN environment variable
2. GITTENSORY_TOKEN environment variable
3. GITTENSORY_MCP_TOKEN environment variable
4. Session token from the config file (stored by gittensory-mcp login)

Session tokens carry a login, expiresAt, and scopes payload 11. Static beta tokens may not have a verifiable session — this is expected behavior for pre-release access.

Verifying your setup#

Two commands help you confirm a working installation:

gittensory-mcp status — reports the local package version, the latest available version on npm, API health, auth state, and source-upload posture 12:

gittensory-mcp status
# @jsonbored/gittensory-mcp: 0.3.0 (latest 0.3.0)
# API: https://gittensory-api.aethereal.dev
# API health: ok
# Auth: authenticated (jsonbored)
# Source upload: disabled

gittensory-mcp doctor — runs a full diagnostic suite covering API health, API compatibility, package version, authentication, source-upload posture, git metadata access, PATH visibility, and local scorer configuration 13:

gittensory-mcp doctor
# Gittensory doctor: ok
# - pass: api_health - API responded from https://gittensory-api.aethereal.dev.
# - pass: version - Installed 0.3.0 matches npm latest 0.3.0.
# - pass: api_compatibility - Local 0.3.0 meets the API minimum 0.3.0.
# - pass: auth - Authenticated as jsonbored; session expires 2026-08-01T00:00:00.000Z.
# - pass: source_upload - Source upload is disabled and unsupported in v1.
# - pass: git_metadata - owner/repo on feature-branch; 4 changed file(s).
# - pass: client_path - gittensory-mcp is visible on PATH.
# - warn: local_scorer - GITTENSOR_SCORE_PREVIEW_CMD is not configured; ...

If doctor reports issues, it also provides specific remediation steps. Run gittensory-mcp doctor --json for structured output suitable for automated checks.

Logging out#

gittensory-mcp logout

This revokes the remote session and removes the local config file.

Running as an MCP Server#

Starting in stdio mode#

To expose Gittensory's intelligence layer to an MCP-compatible AI client, start the package in stdio mode:

gittensory-mcp --stdio

This starts an McpServer named gittensory-local that communicates via StdioServerTransport — reading JSON-RPC messages from stdin and writing responses to stdout 14 15. The server registers all 21 MCP tools and remains alive until the client process exits.

The --stdio flag is what MCP clients use to spawn and communicate with the server. From the client's perspective, Gittensory appears as a local process that accepts tool calls and returns structured JSON results.

How MCP client-server communication works#

In the MCP architecture, the client (e.g., Claude, Cursor, Codex) spawns the server (gittensory-mcp --stdio) as a child process. Communication flows as line-delimited JSON-RPC messages over stdin/stdout:

1. The client sends a tool call request — e.g., gittensory_preflight_current_branch with input parameters
2. The server validates inputs using Zod schemas, collects local git metadata, and calls the Gittensory Worker API
3. The server returns a structured response with a human-readable summary line and a JSON data object
4. The client (and the AI model behind it) uses the response to make decisions

This design keeps all API credentials and local git state on the user's machine. The AI model only sees the structured intelligence output — never raw tokens or source code.

Generating client configuration snippets#

The init-client command prints a ready-to-paste configuration snippet for your preferred tool 16:

gittensory-mcp init-client --print claude
gittensory-mcp init-client --print cursor
gittensory-mcp init-client --print codex

These commands print config only — they do not modify client files. Paste the output into the appropriate config file for your tool (see Integration Examples for full details).

Important: Run gittensory-mcp login before starting your MCP client. The server reads the session token at startup. If no token is configured, tool calls will fail with an authentication error 17.

What Context It Exposes to Agents#

The 21 MCP tools are organized into five capability categories. Together they give agents a complete picture of contribution health — from raw repo signals to scored, ranked next actions — without requiring source code upload.

Repo Intelligence#

PR Preflight & Scoring#

Contributor Decisions#

Decision packs are rebuilt every 6 hours and returned immediately (with a freshness: "rebuilding" flag if stale), ensuring agents always receive actionable context 27.

Current Branch Analysis#

These tools analyze your current local git branch and return all intelligence in a single call. All calls send metadata only — changed file paths, line counts, commit messages, test file lists. No source code leaves your machine 28.

Agent Operations#

The intelligence these tools surface#

Across all five categories, agents gain access to:

• Contributor decision packs — history, contribution patterns, open PR counts, credibility score, queue pressure, and per-repo lane decisions
• Gittensor network stats — registry changes, validator movement, network topology as it affects contribution weight
• Queue health metrics — how backed-up the review queue is per repo, and when it is favorable to open new work
• Collision risk assessment — whether another contributor is working on overlapping files or scope
• Score blockers — the specific factors preventing a PR from being accepted or scoring well
• Lane fit analysis — whether the planned work matches the repo's active maintainer lanes
• Duplicate risk detection — signal from the duplicate and overlap preflight checks
• Credibility assumptions — current and projected credibility given pending merges, open PRs, and approved work
• Maintainer friction signals — indicators that a PR may generate excessive review overhead

Agents use this context to determine whether to proceed with a PR, restructure the work, address blockers first, or wait for better queue conditions — all before a single line of code is submitted upstream.

Preflight Workflow#

The preflight workflow is the core pattern for miners and agents using Gittensory MCP: analyze a local branch before opening a PR, get scored intelligence back, and decide how to proceed — all without uploading source code.

Privacy-preserving by design#

Gittensory's MCP package is built on a strict metadata-only principle. When you run a branch analysis, the package:

1. Reads git metadata locally: changed file paths, line counts, test files, commit messages, branch names, and base/head SHAs
2. Sends only that metadata to the Worker API — no file contents, no diffs, no source tokens
3. Returns enriched intelligence computed server-side against Gittensor network data, contributor history, and scoring models

The GITTENSORY_UPLOAD_SOURCE environment variable is false by default, and setting it to true fails closed — source upload is explicitly unsupported in v1 40. The gittensory_local_status tool confirms this posture at any time:

{
  "sourceUploadDefault": false,
  "sourceUploadSupported": false
}

41

Typical preflight workflow#

Step 1 — Check out or create your branch

git checkout -b feat/my-contribution
# ... make your changes ...

Step 2 — Run the preflight analysis

From the CLI, pass your GitHub login and optionally specify your repo and base branch:

gittensory-mcp analyze-branch --login yourlogin --json

You can optionally pass branch eligibility metadata to model linked-issue assumptions:

gittensory-mcp analyze-branch --login yourlogin \
  --branch-eligibility eligible \
  --json

The --branch-eligibility flag accepts eligible, ineligible, or unknown. Related optional flags include --branch-eligibility-source, --branch-eligibility-reason, --branch-eligibility-checked-at, and --branch-eligibility-stale. These flags model branch eligibility for issue-solving PR assumptions in scoring previews.

Or from an MCP client, call gittensory_preflight_current_branch with your login:

{
  "login": "yourlogin",
  "repoFullName": "owner/repo",
  "baseRef": "origin/main"
}

29

Step 3 — Review the intelligence response

The response includes 42:

• analysis.summary — a one-line summary of the branch state
• analysis.preflight.status — pass, warn, or fail
• analysis.nextActions — ranked list of recommended next actions
• analysis.scoreBlockers — specific factors blocking a good score
• analysis.workspaceIntelligence — detailed local findings:
  • Changed file counts (total, binary, deleted, renamed)
  • Test evidence level
  • Pending commits ahead of base
  • Base freshness status and warnings
  • Branch-quality blockers
  • Account/queue blockers
  • CI hints
  • rerunWhen — condition under which to re-analyze

Step 4 — Address blockers or proceed

If the preflight returns blockers, address them before opening the PR. If the analysis looks clean, use gittensory_prepare_pr_packet or gittensory-mcp agent packet to draft a public-safe PR description 33.

Step 5 — Open the PR

The agent or miner decides to open the PR. Gittensory never opens it automatically.

Situational scenario analysis#

For more precise what-if analysis — for example, when you have PRs pending merge that will change your credibility — pass situational assumptions explicitly 43:

gittensory-mcp analyze-branch --login yourlogin \
  --pending-merged-prs 3 \
  --expected-open-prs 0 \
  --projected-credibility 0.8 \
  --scenario-note "approved PRs expected to merge this week" \
  --json

The same parameters are available as fields in the currentBranchShape input schema for MCP tool calls 44.

Including validation results#

If you run tests or linters locally, you can pass the results to the preflight for inclusion in the analysis:

gittensory-mcp preflight --login yourlogin \
  --validation "passed|npm test|All tests passed in 4.2s" \
  --json

The --validation flag accepts a pipe-delimited string: status|command|summary. Multiple --validation flags are supported for multiple commands 45.

Local score preview adapter#

For more accurate score estimates, you can configure a local scorer command that analyzes your branch metadata and produces token score estimates — entirely on your machine, with no source upload 46:

# Metadata-only scorer (included in the package):
export GITTENSOR_SCORE_PREVIEW_CMD="node $(npm root -g)/@jsonbored/gittensory-mcp/scripts/gittensor-score-preview.mjs"

# Tree-sitter scorer (requires local gittensor checkout):
export GITTENSOR_ROOT=/path/to/gittensor
export GITTENSOR_SCORE_PREVIEW_CMD="python3 $(npm root -g)/@jsonbored/gittensory-mcp/scripts/gittensor-score-preview.py"

The scorer receives branch metadata JSON on stdin and must print a single JSON object to stdout with this shape 47:

{
  "sourceTokenScore": 42,
  "totalTokenScore": 58,
  "sourceLines": 40,
  "testTokenScore": 16,
  "nonCodeTokenScore": 0,
  "warnings": []
}

When no scorer is configured or it fails, the system falls back to metadata-only analysis automatically. Run gittensory-mcp doctor to check scorer configuration and connectivity 48.

Integration Examples#

Generating configuration snippets#

The init-client command prints a ready-to-paste configuration for your preferred MCP client. Use it to get started quickly 16:

gittensory-mcp init-client --print claude # Claude Desktop / Anthropic clients
gittensory-mcp init-client --print cursor # Cursor IDE
gittensory-mcp init-client --print codex # OpenAI Codex / CLI agents
gittensory-mcp init-client --print mcp # Generic MCP JSON config

Add --json to get the config as structured JSON with notes 49.

Note: These commands print configuration only — they do not modify any client files. You must paste the output into your client's config file manually.

Claude Desktop#

Add the following to your claude_desktop_config.json (typically at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "gittensory": {
      "command": "gittensory-mcp",
      "args": ["--stdio"]
    }
  }
}

50

Or generate it automatically:

gittensory-mcp init-client --print claude >> ~/Library/Application\ Support/Claude/claude_desktop_config.json

After saving, restart Claude Desktop. Gittensory tools will appear in Claude's tool panel.

Cursor IDE#

Add the same configuration to Cursor's MCP config file (.cursor/mcp.json in your project or the global Cursor config):

{
  "mcpServers": {
    "gittensory": {
      "command": "gittensory-mcp",
      "args": ["--stdio"]
    }
  }
}

50

Generate it with:

gittensory-mcp init-client --print cursor

OpenAI Codex / CLI agents#

For Codex and other TOML-configured agents, use the Codex snippet format 50:

[mcp_servers.gittensory]
command = "gittensory-mcp"
args = ["--stdio"]

Generate with:

gittensory-mcp init-client --print codex

Using an absolute command path#

If your MCP client does not inherit your shell's PATH (common with GUI applications), the gittensory-mcp binary may not be found. In that case, use the absolute path returned by which gittensory-mcp:

which gittensory-mcp
# /usr/local/bin/gittensory-mcp

Then reference it explicitly in your config:

{
  "mcpServers": {
    "gittensory": {
      "command": "/usr/local/bin/gittensory-mcp",
      "args": ["--stdio"]
    }
  }
}

51

gittensory-mcp doctor reports a client_path check that warns you if the binary is not found on PATH.

Token-based authentication for agent-hosted environments#

In CI pipelines or automated agent runtimes where interactive login is not possible, set the token as an environment variable:

export GITTENSORY_API_TOKEN=your-token-here
gittensory-mcp --stdio

Some MCP clients support passing environment variables in their config:

{
  "mcpServers": {
    "gittensory": {
      "command": "gittensory-mcp",
      "args": ["--stdio"],
      "env": {
        "GITTENSORY_API_TOKEN": "your-token-here"
      }
    }
  }
}

The token priority order is: GITTENSORY_API_TOKEN > GITTENSORY_TOKEN > GITTENSORY_MCP_TOKEN > config file session 10.

Verifying the integration#

After configuring your client:

1. Check local setup: gittensory-mcp status and gittensory-mcp doctor
2. Confirm tools are visible: In Claude, open the tool panel and look for gittensory_* tools. In Cursor, check the MCP tool list in the agent sidebar.
3. Test a tool call: Ask your agent to call gittensory_local_status — it requires no arguments and returns the local package version, API URL, auth state, and git metadata. A successful response confirms end-to-end connectivity.

Available Commands & Tools#

CLI Commands#

The package provides 13 CLI commands for human-friendly access to all capabilities. All commands support --json for structured output 52.

Authentication & Diagnostics#

Branch Analysis#

Agent Commands (copilot-only)#

MCP Tools Reference#

All 21 tools use Zod-validated input schemas 53 and return a structured response containing a human-readable summary string and a JSON data object.

Category 1: Repo Intelligence#

gittensory_get_repo_context

• Purpose: Fetch the canonical repo intelligence bundle
• Input: { owner: string, repo: string }
• Output: Repo intelligence including queue health, scoring model state, lane configuration, and maintainer policies
• Use case: Understand a repo's current review capacity and scoring environment before targeting it for contribution 18

gittensory_get_registry_changes

• Purpose: Return latest cached Gittensor registry change report
• Input: {} (no input required)
• Output: Registry change report with validator movements and network topology updates
• Use case: Determine if network conditions have shifted in a way that affects contribution value 19

gittensory_local_status

• Purpose: Return local MCP status, inferred git repo metadata, and privacy defaults
• Input: { cwd?: string, baseRef?: string, repoFullName?: string }
• Output: Package version, auth state, session expiry, source-upload posture, inferred git metadata
• Use case: Confirm the server is running and has detected the correct repo 20

Category 2: PR Preflight & Scoring#

gittensory_preflight_pr

• Purpose: Validate planned PR metadata against lane, duplicate, test, and queue signals
• Input: { repoFullName, title, body?, labels?, changedFiles?, linkedIssues?, tests?, authorAssociation?, contributorLogin? }
• Output: Preflight status and findings
• Use case: Pre-validate a PR before running local branch analysis 21

gittensory_preflight_local_diff

• Purpose: Inspect local git diff metadata and run preflight without source upload
• Input: { repoFullName, cwd?, baseRef?, contributorLogin?, title?, body?, labels?, linkedIssues?, tests?, commitMessage? }
• Output: Preflight results enriched with local diff metadata (changed files, line counts, test files)
• Use case: Get a full preflight check from a local branch without constructing the PR first 22

gittensory_preview_local_pr_score

• Purpose: Request a private scoring preview for local diff metadata
• Input: All fields from localDiffShape plus optional sourceTokenScore, totalTokenScore, sourceLines, credibility, projectedCredibility, PR state fields, scenarioNotes, and branchEligibility (object with status, source, reason, checkedAt, stale)
• Output: Score estimate with scenario breakdowns, setup guidance if scorer is missing
• Use case: Get a private score estimate before opening a PR 23

gittensory_compare_pr_variants

• Purpose: Compare scoring previews across up to 10 metadata variants
• Input: { variants: localScoreShape[] } (1–10 variants)
• Output: Variants sorted by estimated score, highest first
• Use case: Evaluate different PR structures — different scope, labels, or base branches — before committing to one 24

Category 3: Contributor Decisions#

gittensory_get_decision_pack

• Purpose: Return the canonical private contributor decision pack for a GitHub login
• Input: { login: string }
• Output: Full decision pack with contributor history, queue health, lane recommendations, credibility, per-repo decisions, and freshness metadata
• Use case: Understand a contributor's full context before planning next work 25

gittensory_explain_repo_decision

• Purpose: Return the contributor/repo decision from the decision pack, scoped to one repo
• Input: { login: string, owner: string, repo: string }
• Output: Repo-scoped decision — whether to contribute, lane fit, friction signals
• Use case: Get a focused recommendation for one specific repo 26

Category 4: Current Branch Analysis#

All six current-branch tools share the currentBranchShape input 44:

• Required: login
• Optional: cwd, repoFullName, baseRef, headRef, branchName, title, body, labels, linkedIssues
• Scenario fields: pendingMergedPrCount, expectedOpenPrCountAfterMerge, projectedCredibility, scenarioNotes
• Validation: array of { command, status, summary?, durationMs?, exitCode? } objects
• Branch eligibility: optional branchEligibility object with status ("eligible" | "ineligible" | "unknown"), source, reason, checkedAt, and stale fields — models branch eligibility for issue-solving PR assumptions when the standard issue mode is used

gittensory_preflight_current_branch — PR readiness: preflight status, workspace intelligence, PR packet 29

gittensory_preview_current_branch_score — Private scoreability: score preview, scenario score preview, score blockers, rerun condition 30

gittensory_rank_local_next_actions — Ranked next actions by reward/risk and review friction, with rewardRisk breakdown 31

gittensory_explain_local_blockers — Full blocker explanation: score blockers, branch-quality blockers, account-state blockers, base freshness, local findings 32

gittensory_prepare_pr_packet — Public-safe PR packet ready for maintainer sharing 33

gittensory_compare_local_variants — Compare up to 10 branch variants; returns preflight status, score blockers, top action, and PR packet per variant, sorted by priority score 34

Category 5: Agent Operations#

gittensory_agent_plan_next_work

• Input: { login, objective?: string, repoFullName?: string }
• Output: Deterministic action plan with ranked actions, summary, and rerun condition 35

gittensory_agent_start_run

• Input: { objective, actorLogin, targetRepoFullName?, targetPullNumber?, targetIssueNumber? }
• Output: Queued run record with runId for polling 36

gittensory_agent_get_run

• Input: { runId: string }
• Output: Full AgentRunBundle — run record, actions, context snapshots, summary 37

gittensory_agent_explain_next_action

• Input: { login, objective?: string, repoFullName?: string }
• Output: Blocker context plus topAction with recommendation and rerunWhen 38

gittensory_agent_prepare_pr_packet

• Input: currentBranchShape
• Output: Public-safe PR packet drafted by the agent orchestrator 39

Copilot-Only Next-Action Planning#

The design philosophy#

Gittensory is built on a single principle: suggestions, not autonomy. The MCP package never makes autonomous decisions on your behalf. It ranks, explains, preflights, and drafts — but it does not edit code, open PRs, post comments, close issues, merge pull requests, or apply labels without an explicit user- or maintainer-triggered action 54.

This is not a limitation — it is a deliberate architectural choice. Core decisions are rule-based rather than AI-generated, making the system deterministic and auditable 6. When an agent reads a Gittensory recommendation, it knows exactly what signals produced that recommendation and can verify the reasoning. The human or agent in the loop retains full control.

How next-action planning works#

The base-agent planner runs a deterministic pipeline: it fetches contributor evidence, loads signal snapshots, retrieves official Gittensor stats, builds or refreshes the contributor decision pack, and generates a ranked list of actions using the DecisionActionKind taxonomy 27.

Two tools expose this planning:

gittensory_agent_plan_next_work — returns a full action plan for a contributor:

{
  "login": "yourlogin",
  "repoFullName": "owner/repo"
}

The response includes:

• summary — one-line description of the recommended path forward
• actions — ranked list of next actions, each with actionType, recommendation, rerunWhen, and priorityScore
• recommendedRerunCondition — when to re-run the planner (e.g., "after pending PRs merge")

gittensory_rank_local_next_actions — returns the same ranked actions scoped to the current local branch, enriched with rewardRisk context from the branch-level analysis 31.

Example next-action types#

The planner uses a taxonomy of action kinds to structure its recommendations 27. Typical examples:

Each action includes a recommendation string explaining why this action is prioritized and a rerunWhen field indicating what event should trigger a re-evaluation.

CLI agent workflow#

From the terminal:

# Get the full next-work plan
gittensory-mcp agent plan --login yourlogin --repo owner/repo --json

# Check the status of a running plan
gittensory-mcp agent status <run-id> --json

# Get a human-readable explanation of the top action
gittensory-mcp agent explain <run-id> --json

# Draft a public-safe PR packet
gittensory-mcp agent packet --login yourlogin --repo owner/repo --base origin/main --json

55

Public-safe output#

All output from agent and packet commands passes through a forbidden-words filter before leaving the system. Private signals — wallet addresses, raw trust scores, payout amounts, hotkeys, coldkeys, and private reviewability data — are stripped from any public-facing output 56.

This means the PR packet generated by gittensory_prepare_pr_packet or gittensory agent packet is safe to paste directly into a GitHub PR description. It contains context useful to maintainers without leaking any sensitive scoring or identity context.

What agents should do with recommendations#

Gittensory's MCP surface is designed to be consumed by coding agents as context for decision-making, not as commands to execute. A well-integrated agent:

1. Calls gittensory_agent_plan_next_work or gittensory_rank_local_next_actions to understand the current situation
2. Reads the ranked action list and recommendation strings
3. Uses that context to decide on its own next step — whether to continue working on the branch, open a PR, address a blocker, or wait
4. Calls gittensory_prepare_pr_packet to draft the PR description when ready
5. Leaves the actual PR creation to the human or to an explicitly authorized automation step

The intelligence layer informs the decision. The decision itself belongs to the agent or the human.