@pathmode/mcp-server 1.1.0

package/README.md

@@ -0,0 +1,244 @@
+# @pathmode/mcp-server
+
+Connect Claude Code, Cursor, and other AI agents to your [Pathmode](https://pathmode.io) Intent Layer.
+
+Get strategic context, dependency graph analysis, and structured implementation prompts — so your AI agent builds the right thing, not just any thing.
+
+## Features
+
+- **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
+
+## Quick Start
+
+```bash
+npx @pathmode/mcp-server
+```
+
+## Setup
+
+### Claude Desktop
+
+Add to `~/.config/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pathmode": {
+      "command": "npx",
+      "args": ["@pathmode/mcp-server"],
+      "env": {
+        "PATHMODE_API_KEY": "pm_live_..."
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "pathmode": {
+      "command": "npx",
+      "args": ["@pathmode/mcp-server"],
+      "env": {
+        "PATHMODE_API_KEY": "pm_live_..."
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "pathmode": {
+      "command": "npx",
+      "args": ["@pathmode/mcp-server"],
+      "env": {
+        "PATHMODE_API_KEY": "pm_live_..."
+      }
+    }
+  }
+}
+```
+
+### Local Mode (Offline)
+
+Read `intent.md` files from your project directory without an API key:
+
+```json
+{
+  "mcpServers": {
+    "pathmode": {
+      "command": "npx",
+      "args": ["@pathmode/mcp-server", "--local"]
+    }
+  }
+}
+```
+
+## 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` |
+
+Get your API key from **Settings > API Keys** in the [Pathmode app](https://pathmode.io).
+
+## Tools
+
+### 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 |
+
+### 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 |
+
+### 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 |
+
+### 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 |
+
+## 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`.
+
+**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.
+
+**Connection timeout**
+Ensure your API key is valid and has the correct scopes (read, write). 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.
+
+**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.
+
+**Third-party sharing:** No data is shared with third parties. The server communicates exclusively with the Pathmode API.
+
+**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).
+
+**Contact:** For privacy inquiries, contact privacy@pathmode.io.
+
+## Support
+
+- Issues: [github.com/pathmode/mcp-server/issues](https://github.com/pathmode/mcp-server/issues)
+- Documentation: [pathmode.io/docs](https://pathmode.io/docs)
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Pathmode API Client for MCP Server
+ * Replicates the CLI api-client for standalone packaging.
+ */
+export interface PathmodeConfig {
+    apiKey: string;
+    apiUrl: string;
+    workspaceId: string;
+}
+export interface ApiIntent {
+    id: string;
+    workspaceId: string;
+    journeyId?: string;
+    stageId?: string;
+    stageName?: string;
+    status: string;
+    version: number;
+    objective: string;
+    problemSeverity?: string;
+    userGoal: string;
+    outcomes: string[];
+    healthMetrics: string[];
+    strategicAlignment?: string;
+    alignmentNotes?: string;
+    preconditions: Record<string, any>;
+    context: Record<string, any>;
+    constraints: string[];
+    verification: Record<string, any>;
+    externalLinks: any[];
+    createdAt: string;
+    updatedAt: string;
+    shippedAt?: string;
+    verifiedAt?: string;
+    edgeCases: {
+        id: string;
+        scenario: string;
+        expectedBehavior: string;
+    }[];
+    evidenceIds: string[];
+    relations: {
+        targetId: string;
+        type: string;
+    }[];
+}
+export interface ApiWorkspace {
+    id: string;
+    name: string;
+    urlKey?: string;
+    tags: string[];
+    strategy: {
+        vision?: string;
+        tradeoffs?: string[];
+        nonNegotiables?: string[];
+        architecturePrinciples?: string[];
+    } | null;
+    constitutionRules: {
+        id: string;
+        category: string;
+        text: string;
+        isActive: boolean;
+        createdAt: string;
+    }[];
+}
+export declare function loadConfig(): PathmodeConfig | null;
+export declare class PathmodeClient {
+    private apiKey;
+    private apiUrl;
+    private workspaceId;
+    constructor(config: PathmodeConfig);
+    private fetch;
+    listIntents(status?: string): Promise<ApiIntent[]>;
+    getIntent(id: string): Promise<ApiIntent>;
+    getIntentPrompt(id: string, agentType?: string, mode?: string): Promise<{
+        prompt: string;
+        json: object;
+    }>;
+    updateIntentStatus(id: string, status: string): Promise<any>;
+    logNote(intentId: string, note: string, source?: string): Promise<any>;
+    getWorkspace(): Promise<ApiWorkspace>;
+    getConstitution(): Promise<any>;
+    exportClaudeMd(): Promise<string>;
+    exportContext(format: 'claude-md' | 'cursorrules' | 'intent-md', intentId?: string): Promise<string>;
+}

package/dist/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"","sourceRoot":"","sources":["file:///Users/jannelammi/code/Pathmode/packages/mcp-server/src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pathmode MCP Server
+ * Connects Claude Code, Cursor, and other AI agents to your Intent Layer.
+ *
+ * Usage:
+ *   npx @pathmode/mcp-server            # Cloud mode (uses ~/.pathmode/config.json)
+ *   npx @pathmode/mcp-server --local     # Local mode (reads intent.md from cwd)
+ *
+ * Add to .claude/settings.json:
+ *   {
+ *     "mcpServers": {
+ *       "pathmode": {
+ *         "command": "npx",
+ *         "args": ["@pathmode/mcp-server"],
+ *         "env": { "PATHMODE_API_KEY": "pm_live_..." }
+ *       }
+ *     }
+ *   }
+ */
+export {};

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"","sourceRoot":"","sources":["file:///Users/jannelammi/code/Pathmode/packages/mcp-server/src/index.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;GAkBG"}