@pathmode/mcp-server

Deterministic intent preflight before your agent builds: six calibrated gates, keyless, no model call.

No signup and no API key. Specs live in intent.md in your repo, as plain markdown you own.

This repository dogfoods the same workflow: read its intent.md.

check_intent_readiness is the first move: it scores a spec against the six gates of the intent.md profile and names the exact blockers, with no model call, so the same spec always gets the same verdict. The Intent Compiler below drafts and sharpens the spec that preflight grades.

Intent Compiler

The Intent Compiler turns Claude Code into a Socratic product thinking partner. Describe a problem, paste a support ticket, or explain what's broken — Claude challenges vague thinking, asks pointed questions, runs live quality checks on weak fields, and builds a structured spec.

> Help me write an intent spec for our checkout flow

  What's broken about it? When you say "checkout flow" — is the whole
  thing failing, or is there one specific moment where users bail?

> Payment step times out and users get confused

  When you say "times out" — is that 5 seconds or 30? And what does
  the user actually see? A spinner? A blank screen? An error?

> About 8 seconds, they see a spinner with no feedback

  Proposed Objective: "Reduce cart abandonment caused by payment step
  timeouts exceeding 3 seconds, where users see a spinner with no
  status feedback or recovery path."

  Does that capture it, or is there more to the pain?

When the spec is ready, Claude saves it as intent.md and optionally exports as .cursorrules, CLAUDE.md, or AGENTS.md (Codex/Cursor) — so every AI agent in your project sees the intent as its implementation context.

Quick Start

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "pathmode": {
      "command": "npx",
      "args": ["@pathmode/mcp-server"]
    }
  }
}

Then in Claude Code:

> Help me write an intent spec for [your problem here]

That's it. No API key needed.

What You Get

intent.md — Structured spec with YAML frontmatter, written in the open IntentSpec format:

---
id: "intent_17291..."
version: 1
status: "draft"
readiness: "passed 6/6"
---
# Fix Checkout Payment Timeout

## Objective
Reduce cart abandonment caused by payment step
timeouts exceeding 3 seconds.

## Outcomes
- [ ] Payment completes in under 3 seconds (p95)
- [ ] Users see real-time status during processing
- [ ] Failed payments show actionable error with retry

## Edge Cases
- **Network timeout during payment**: Show retry button, no double-charge
- **Unknown provider status**: Hold order, notify user within 30s

The readiness line is the deterministic preflight verdict, stamped on every save — "passed 6/6", or "failed N/6" naming the blocking gates — so any agent reading the file knows whether the spec cleared the gate without re-running it. Specs exported from a Pathmode workspace also carry source: (the canonical intent URL — the file is a working copy of that record) and evidence: (how many linked evidence items back it).

.cursorrules — Agent-directive format for Cursor:

# CURRENT OBJECTIVE
You are implementing: "Fix Checkout Payment Timeout"

# SUCCESS OUTCOMES
Your implementation MUST satisfy ALL of these:
- Payment completes in under 3 seconds (p95)
- Users see real-time status during processing
- Failed payments show actionable error with retry

CLAUDE.md — Appends a <!-- PATHMODE:START --> section so Claude Code sees the intent in every conversation.

Skill Pack for Claude Code

The package also ships 9 Claude Code skills that auto-trigger based on what you ask — no slash commands required.

| Skill | Use when | |-------|----------| | setup-pathmode-workflow | First-time project setup (test commands, issue tracker, status conventions) | | compile-intent | Building a structured spec for what to ship | | preflight | Running the deterministic six-gate readiness verdict before implementation | | implement-intent | Implementing a repository intent only after Preflight and required human authorization | | verify-intent | Designing the executable feedback loop for a spec | | grill-intent | Stress-testing an existing spec for weaknesses | | split-intent-to-issues | Breaking a spec into Linear / Jira / GitHub Issues tickets | | review-against-intent | Checking code changes against intent outcomes | | handoff-intent | Capturing decisions at end of session |

Install after running the MCP setup:

npx @pathmode/mcp-server install-skills            # project-local (.claude/skills/)
npx @pathmode/mcp-server install-skills --global   # global (~/.claude/skills/)

Restart Claude Code. The skills register at session start and auto-invoke when your request matches their description. See skills/README.md for details.

Intent Compiler Tools

| Tool | Description | |------|-------------| | check_intent_readiness | The deterministic preflight: six calibrated gates, no model call, the same spec always gets the same verdict. With no arguments it resolves the intent.md bound to this repository | | confirm_intent_dimension | Resolve a dimension the gate READ but could not confirm (it matches a fixed English vocabulary and misses valid phrasing, including other languages), or waive one as not applicable | | intent_save | Save an intent spec to intent.md in the project root | | intent_export | Export as .cursorrules, a CLAUDE.md or AGENTS.md section, or an Outcomes rubric | | intent_import | Adopt an existing OpenSpec change as the intent record; the change folder is never modified |

Intent Compiler Prompt

| Prompt | Description | |--------|-------------| | compile-intent | Start a Socratic conversation to build an intent spec |

Team Features (API Key Required)

For teams shipping with AI agents, connect to your Pathmode workspace for dependency tracking, strategic context, and governance.

Setup with API Key

Automatic setup:

npx @pathmode/mcp-server@latest setup pm_live_...

{
  "mcpServers": {
    "pathmode": {
      "command": "npx",
      "args": ["@pathmode/mcp-server"],
      "env": {
        "PATHMODE_API_KEY": "pm_live_..."
      }
    }
  }
}

Works with Claude Code (.mcp.json in the project root), Claude Desktop (claude_desktop_config.json), and Cursor (.cursor/mcp.json).

Get your API key from Settings > API Keys in the Pathmode app.

Adopt an existing repository intent

If your repository already contains a preflighted intent.md, start from the repo onboarding door in Pathmode. After you choose a workspace and Product, the page gives you a short-lived one-time command:

npx @pathmode/mcp-server@latest adopt pm_adopt_...

Run it from the repository root. The command uploads the existing spec, adds only Pathmode's canonical identity fields to its frontmatter, and configures that repository to use the selected workspace. The one-time code expires after 15 minutes and is never stored in the repository.

The safe repository binding lives in .pathmode/config.json. The API key lives separately at ~/.pathmode/workspaces/<workspace-id>.json, so connecting one repository does not repoint other repositories on the same machine. Add .pathmode/ to .gitignore if your team does not want to commit the non-secret workspace binding.

Local Mode (Offline)

Local mode is the default when no API key is configured. It reads and writes intent.md in your project directory, and nothing leaves your machine. Local mode includes check_intent_readiness — the deterministic preflight that scores a spec against six calibrated gates and names the exact blockers, with no model call (the same gate that runs at preflight.pathmode.io). The plain block is a complete keyless setup:

{
  "mcpServers": {
    "pathmode": {
      "command": "npx",
      "args": ["@pathmode/mcp-server"]
    }
  }
}

Pass --local only to force local mode when an API key is configured:

{
  "mcpServers": {
    "pathmode": {
      "command": "npx",
      "args": ["@pathmode/mcp-server", "--local"]
    }
  }
}

Configuration

| Method | Details | |--------|---------| | Environment variable | PATHMODE_API_KEY=pm_live_... | | Repository binding | .pathmode/config.json, with its key stored outside the repo in ~/.pathmode/workspaces/<workspace-id>.json | | Config file | ~/.pathmode/config.json with apiKey, apiUrl, workspaceId | | Local mode | Automatic when no key is found. Reads intent.md and .pathmode/intents/*.md; --local forces it | | No config | Local mode. The Intent Compiler needs no configuration |

Team Tools

Intent Management

| Tool | Description | |------|-------------| | get_current_intent | Get the active intent (first approved, or most recent) | | get_intent | Get a single intent by ID with full details | | get_intent_evidence | Dereference one intent's repo-safe evidence IDs with trust tiers | | propose_spec_change | Propose an exact, revision-bound correction for a person to accept; stores the observation as unreviewed agent evidence | | list_intents | List all intents, optionally filtered by status | | search_intents | Search intents by keyword across goals, objectives, and outcomes | | create_intent | Create an intent in the workspace without writing a file. Inside a repo prefer intent_save | | update_intent | Update an existing intent's content; pass only the fields you want to change | | update_intent_status | Move an intent through draft > validated > approved > shipped > verified. Not for work delivered by pull request: name the intent on the branch or in the PR body and let the merge grade the real diff and set shipped. Use it for work that never appears in a PR, and for shipped > verified once the outcome is confirmed in production |

PM-to-Repository Change Requests

| Tool | Description | |------|-------------| | list_intent_change_requests | Discover structured PM requests workspace-wide, or narrow to one repository-authority intent; reading records agent consumption | | get_intent_change_request | Read one request with its exact base revision, operation, proposed value, and reason | | reject_intent_change_request | Report an unworkable request with an API-key-attributed reason |

Apply a request by editing intent.md, then call intent_save with both changeRequestId and baseRepoBodyRevision. Pathmode compares immutable snapshots and closes the request itself; an agent cannot submit a success flag or diff.

Delivery & Verification

| Tool | Description | |------|-------------| | verify_implementation | Grade an implementation against the spec by reading the pull request. Pass prUrl and Pathmode fetches the diff itself, grading each outcome, constraint, constitution rule, edge case and verification check against what the code actually shows, with citations. Describing your own work instead is weaker evidence and the result says so | | record_implementation_finding | The spec was wrong: record what it assumed and what building revealed. Targeting a verification check flips that check to failing. Open findings ride into future agent prompts until a human reconciles them | | record_implementation_context | Hand back what the repo actually looks like where this intent lands: files and modules involved, how it behaves today, what a change would risk, how to verify it | | record_outcome_measurement | What actually happened to an outcome after it shipped. The spec said what should change; this says whether it did | | log_implementation_note | The handoff to the next session. The newest notes render into the next agent's execution prompt, so write each one self-contained |

An agent never settles its own delivery. The merge owns the shipped transition for PR-delivered work, and a proposed correction (propose_spec_change) waits for a signed-in person to accept it.

Evidence

| Tool | Description | |------|-------------| | query_evidence | Search evidence items by product, type, severity, or text; returns IDs that can be linked to intents | | create_evidence | Create an evidence item: a discovered bug, a user quote, a behavioral observation, a feature request | | link_evidence | Link or unlink evidence to an intent, establishing traceability between user problems and planned solutions |

Strategic Analysis

| Tool | Description | |------|-------------| | analyze_intent_graph | Analyze dependency graph for critical path, cycles, bottlenecks | | get_intent_relations | Get the dependency graph for a specific intent |

Context & Export

| Tool | Description | |------|-------------| | export_context | Generate CLAUDE.md, AGENTS.md (Codex/modern Cursor), .cursorrules, or intent.md files. For claude-md/agents-md, optionally pass a product ID; for cursorrules/intent-md, product is derived from the resolved intent | | get_agent_prompt | Get a structured execution prompt for an intent | | get_workspace | Get workspace details including strategy, active products, and constitution | | get_constitution | Get mandatory constraint rules for the workspace | | sync_context | Write this workspace's canonical context into the repo's CLAUDE.md or AGENTS.md, idempotently, replacing the PATHMODE-marked section in place |

Team Prompts

| Prompt | Description | |--------|-------------| | implement-intent | Full implementation workflow for a specific intent | | review-risks | Analyze the intent graph for architectural risks | | what-next | Suggest the highest-priority intent to work on next |

Resources

| URI | Description | |-----|-------------| | intent://current | Currently active intent | | intent://graph | Full intent dependency graph | | intent://workspace-strategy | Workspace vision, principles, and active constitution rules |

Troubleshooting

"No Pathmode configuration found" This no longer causes an error. The Intent Compiler works without any configuration. Team features require an API key.

Team tools are missing from the tool list In local mode the cloud-only tools are not registered, so the agent only sees tools that work. Configure an API key (setup pm_live_xxx) to get intent management, evidence, and graph tools.

Connection timeout Ensure your API key is valid and has the correct scopes. Check your network connection to pathmode.io.

setup starts the server instead of the installer Use the latest package version:

npx @pathmode/mcp-server@latest setup pm_live_...

As a fallback, you can bypass setup entirely by setting the key directly in the MCP config:

{
  "mcpServers": {
    "pathmode": {
      "command": "npx",
      "args": ["@pathmode/mcp-server"],
      "env": {
        "PATHMODE_API_KEY": "pm_live_..."
      }
    }
  }
}

Privacy Policy

This MCP server connects to the Pathmode API (pathmode.io) to read and write intent specifications, workspace data, and constitution rules on behalf of the authenticated user.

The Intent Compiler works entirely offline — specs are saved to your project directory and their contents are never sent to Pathmode servers.

Data collected (team features only): The server transmits your API key for authentication and sends/receives workspace data via the Pathmode API. It also reports two usage signals: that a client launched (the client's name and version), and, for each tool that runs, the tool's name and whether it succeeded — including tools such as intent_save that write only to your project. Those signals carry nothing else: no arguments, no spec content, no file paths, nothing read out of your repository.

Keyless local mode sends nothing. With no API key configured, the server makes no network request at all — no usage signals and no telemetry of any kind.

Data storage: The MCP server stores intent.md and, when a repository is adopted, a non-secret binding in .pathmode/config.json plus its API key in ~/.pathmode/workspaces/<workspace-id>.json. The legacy setup command stores configuration in ~/.pathmode/config.json. Persistent workspace data is stored in Pathmode's cloud infrastructure.

Third-party sharing: No data is shared with third parties. The server communicates exclusively with the Pathmode API.

Full privacy policy: pathmode.io/privacy

Links

• IntentSpec — the open specification for the intent.md files this server writes
• The intent.md profile — the six checks check_intent_readiness scores against
• Preflight — interactive readiness check and local workflow setup
• Pathmode — full platform for teams
• Issues

License

MIT