@pathmode/mcp-server 1.2.0 → 1.2.1

package/README.md

@@ -1,45 +1,36 @@
 # @pathmode/mcp-server
 
-Connect Claude Code, Cursor, and other AI agents to your [Pathmode](https://pathmode.io) Intent Layer.
+Build structured intent specs through Socratic AI conversation — right in your terminal.
 
-Get strategic context, dependency graph analysis, and structured implementation prompts — so your AI agent builds the right thing, not just any thing.
+No signup. No API key. Just add the MCP server and start talking.
 
-## Features
+## Intent Compiler
 
-- **Intent context** — Structured specs with objectives, outcomes, constraints, and edge cases
-- **Dependency graph analysis** — Critical path, cycle detection, bottleneck identification
-- **Context export** — Generate CLAUDE.md, .cursorrules, and intent.md files
-- **Workspace strategy** — Vision, non-negotiables, architecture principles
-- **Constitution rules** — Mandatory constraints for all implementations
-- **Implementation tracking** — Status updates and technical decision logging
+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, and builds a structured spec.
 
-## Quick Start
-
-```bash
-npx @pathmode/mcp-server
 ```
+> Help me write an intent spec for our checkout flow
 
-## Setup
+  What's broken about it? When you say "checkout flow" — is the whole
+  thing failing, or is there one specific moment where users bail?
 
-### Claude Desktop
+> Payment step times out and users get confused
 
-Add to `~/.config/Claude/claude_desktop_config.json`:
+  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?
 
-```json
-{
-  "mcpServers": {
-    "pathmode": {
-      "command": "npx",
-      "args": ["@pathmode/mcp-server"],
-      "env": {
-        "PATHMODE_API_KEY": "pm_live_..."
-      }
-    }
-  }
-}
+> 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?
 ```
 
-### Claude Code
+When the spec is ready, Claude saves it as `intent.md` and optionally exports as `.cursorrules` or `CLAUDE.md` — so every AI agent in your project sees the intent as its implementation context.
+
+### Quick Start
 
 Add to `.claude/settings.json`:
 
@@ -48,18 +39,79 @@ Add to `.claude/settings.json`:
   "mcpServers": {
     "pathmode": {
       "command": "npx",
-      "args": ["@pathmode/mcp-server"],
-      "env": {
-        "PATHMODE_API_KEY": "pm_live_..."
-      }
+      "args": ["@pathmode/mcp-server"]
     }
   }
 }
 ```
 
-### Cursor
+Then in Claude Code:
 
-Add to `.cursor/mcp.json`:
+```
+> 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:
+```markdown
+---
+id: "intent_17291..."
+version: 1
+status: "draft"
+---
+# 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
+```
+
+**.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.
+
+### Intent Compiler Tools
+
+| Tool | Description |
+|------|-------------|
+| `intent_save` | Save an intent spec to `intent.md` in the project root |
+| `intent_export` | Export as `.cursorrules` or `CLAUDE.md` section |
+
+### 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](https://pathmode.io) workspace for dependency tracking, strategic context, and governance.
+
+### Setup with API Key
 
 ```json
 {
@@ -75,6 +127,10 @@ Add to `.cursor/mcp.json`:
 }
 ```
 
+Works with Claude Code (`.claude/settings.json`), Claude Desktop (`claude_desktop_config.json`), and Cursor (`.cursor/mcp.json`).
+
+Get your API key from **Settings > API Keys** in the [Pathmode app](https://pathmode.io).
+
 ### Local Mode (Offline)
 
 Read `intent.md` files from your project directory without an API key:
@@ -90,46 +146,45 @@ Read `intent.md` files from your project directory without an API key:
 }
 ```
 
-## Configuration
+### Configuration
 
 | Method | Details |
 |--------|---------|
 | Environment variable | `PATHMODE_API_KEY=pm_live_...` |
 | Config file | `~/.pathmode/config.json` with `apiKey`, `apiUrl`, `workspaceId` |
 | Local mode | `--local` flag — reads `intent.md` and `.pathmode/intents/*.md` |
+| No config | Intent Compiler works without any configuration |
 
-Get your API key from **Settings > API Keys** in the [Pathmode app](https://pathmode.io).
-
-## Tools
+### Team Tools
 
-### Intent Management
+#### Intent Management
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `get_current_intent` | Get the active intent (first approved, or most recent) | readOnly |
-| `get_intent` | Get a single intent by ID with full details | readOnly |
-| `list_intents` | List all intents, optionally filtered by status | readOnly |
-| `search_intents` | Search intents by keyword across goals, objectives, and outcomes | readOnly |
-| `update_intent_status` | Update intent status (draft > validated > approved > shipped > verified) | write |
-| `log_implementation_note` | Record a technical decision or implementation note | write |
+| 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 |
+| `list_intents` | List all intents, optionally filtered by status |
+| `search_intents` | Search intents by keyword across goals, objectives, and outcomes |
+| `update_intent_status` | Update intent status (draft > validated > approved > shipped > verified) |
+| `log_implementation_note` | Record a technical decision or implementation note |
 
-### Strategic Analysis
+#### Strategic Analysis
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `analyze_intent_graph` | Analyze dependency graph for critical path, cycles, bottlenecks, and risks | readOnly |
-| `get_intent_relations` | Get the dependency graph for a specific intent | readOnly |
+| 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
+#### Context & Export
 
-| Tool | Description | Annotations |
-|------|-------------|-------------|
-| `export_context` | Generate CLAUDE.md, .cursorrules, or intent.md files | readOnly |
-| `get_agent_prompt` | Get a structured execution prompt for an intent | readOnly |
-| `get_workspace` | Get workspace details including strategy and constitution | readOnly |
-| `get_constitution` | Get mandatory constraint rules for the workspace | readOnly |
+| Tool | Description |
+|------|-------------|
+| `export_context` | Generate CLAUDE.md, .cursorrules, or intent.md files |
+| `get_agent_prompt` | Get a structured execution prompt for an intent |
+| `get_workspace` | Get workspace details including strategy and constitution |
+| `get_constitution` | Get mandatory constraint rules for the workspace |
 
-### Prompts
+#### Team Prompts
 
 | Prompt | Description |
 |--------|-------------|
@@ -137,7 +192,7 @@ Get your API key from **Settings > API Keys** in the [Pathmode app](https://path
 | `review-risks` | Analyze the intent graph for architectural risks |
 | `what-next` | Suggest the highest-priority intent to work on next |
 
-### Resources
+#### Resources
 
 | URI | Description |
 |-----|-------------|
@@ -145,99 +200,37 @@ Get your API key from **Settings > API Keys** in the [Pathmode app](https://path
 | `intent://graph` | Full intent dependency graph |
 | `intent://workspace-strategy` | Workspace vision, principles, and active constitution rules |
 
-## Usage Examples
-
-### Example 1: Get Implementation Context
-
-**User prompt:** "What should I implement next?"
-
-**Expected tool calls:**
-1. `get_current_intent` — Fetches the first approved intent
-2. `get_agent_prompt` with `intentId` and `mode: "execute"` — Gets the structured implementation prompt
-
-**Expected output:** A full specification with objective, observable outcomes, constraints, edge cases, and verification steps that the AI agent uses to plan and execute the implementation.
-
----
-
-### Example 2: Analyze Architectural Risks
-
-**User prompt:** "Are there any risks in our intent dependency graph?"
-
-**Expected tool calls:**
-1. `analyze_intent_graph` with `analysis: "full"` — Runs complete graph analysis
-
-**Expected output:**
-```json
-{
-  "summary": { "total": 12, "statusDistribution": { "draft": 3, "approved": 5, "shipped": 4 } },
-  "criticalPath": [
-    { "id": "abc", "userGoal": "User authentication", "status": "shipped" },
-    { "id": "def", "userGoal": "Role-based access control", "status": "approved" },
-    { "id": "ghi", "userGoal": "Admin dashboard", "status": "draft" }
-  ],
-  "cycles": [],
-  "bottlenecks": [
-    { "id": "def", "userGoal": "Role-based access control", "dependentCount": 4, "status": "approved" }
-  ],
-  "orphanCount": 2
-}
-```
-
-The AI agent summarizes: the critical path has 3 steps, "Role-based access control" is a bottleneck blocking 4 other intents and should be prioritized, and 2 intents have no relationships.
-
----
-
-### Example 3: Generate a CLAUDE.md Context File
-
-**User prompt:** "Generate a CLAUDE.md for this project"
-
-**Expected tool calls:**
-1. `export_context` with `format: "claude-md"` — Generates workspace context
-
-**Expected output:** A markdown file containing workspace strategy, active constitution rules, and all approved intents formatted as structured context that can be added to any project's `CLAUDE.md` file. The AI agent can write this directly to disk.
-
----
-
-### Example 4: Search and Track Implementation
-
-**User prompt:** "Find all intents related to authentication and mark the login one as shipped"
-
-**Expected tool calls:**
-1. `search_intents` with `query: "authentication"` — Finds matching intents
-2. `update_intent_status` with `intentId` and `status: "shipped"` — Updates the login intent
-3. `log_implementation_note` — Documents what was implemented
-
-**Expected output:** The search returns matching intents, the status is updated, and a note is logged documenting the implementation approach.
-
 ## Troubleshooting
 
 **"No Pathmode configuration found"**
-Set the `PATHMODE_API_KEY` environment variable or create `~/.pathmode/config.json`.
+This no longer causes an error. The Intent Compiler works without any configuration. Team features require an API key.
 
 **Tools return "not available in local mode"**
-Most tools require cloud mode. Set up an API key, or use `--local` for basic intent reading from `intent.md` files.
+Most team tools require cloud mode. Set up an API key, or use `--local` for basic intent reading.
 
 **Connection timeout**
-Ensure your API key is valid and has the correct scopes (read, write). Check your network connection to `pathmode.io`.
+Ensure your API key is valid and has the correct scopes. Check your network connection to `pathmode.io`.
 
 ## 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.
 
-**Data collected:** The server transmits your API key for authentication and sends/receives workspace data (intents, constitution rules, workspace strategy) via the Pathmode API.
+The **Intent Compiler** works entirely offline — no data is sent to Pathmode servers. Specs are saved locally to your project directory.
 
-**Data storage:** The MCP server itself does not store any data locally (except in `--local` mode where it reads existing `intent.md` files from your project directory). All persistent data is stored in Pathmode's cloud infrastructure.
+**Data collected (team features only):** The server transmits your API key for authentication and sends/receives workspace data via the Pathmode API.
 
-**Third-party sharing:** No data is shared with third parties. The server communicates exclusively with the Pathmode API.
+**Data storage:** The MCP server does not store data locally (except `intent.md` files it creates and in `--local` mode). Persistent data is stored in Pathmode's cloud infrastructure.
 
-**Data retention:** Data retention follows Pathmode's standard data retention policies. See the full privacy policy at [https://pathmode.io/privacy](https://pathmode.io/privacy).
+**Third-party sharing:** No data is shared with third parties. The server communicates exclusively with the Pathmode API.
 
-**Contact:** For privacy inquiries, contact privacy@pathmode.io.
+Full privacy policy: [pathmode.io/privacy](https://pathmode.io/privacy)
 
-## Support
+## Links
 
-- Issues: [github.com/pathmodeio/mcp-server/issues](https://github.com/pathmodeio/mcp-server/issues)
-- Documentation: [github.com/pathmodeio/mcp-server](https://github.com/pathmodeio/mcp-server#readme)
+- [Intent Compiler page](https://pathmode.io/intent-compiler) — Overview and setup guide
+- [Try in browser](https://pathmode.io/sandbox) — Interactive sandbox, no install needed
+- [Pathmode](https://pathmode.io) — Full platform for teams
+- [Issues](https://github.com/pathmodeio/mcp-server/issues)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathmode/mcp-server",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Pathmode MCP Server — Build structured intent specs through Socratic AI conversation (zero-config), or connect to your Intent Layer for strategic context, dependency graphs, and implementation prompts.",
   "main": "dist/index.js",
   "bin": {