agent-planner-mcp 0.5.0 → 0.5.1

package/README.md

@@ -1,363 +1,205 @@
-# Planning System MCP Server
+# AgentPlanner MCP Server
 
-A Model Context Protocol (MCP) server interface for the Planning System API, enabling AI agents to interact with planning data through powerful, efficient tools.
+[![npm](https://img.shields.io/npm/v/agent-planner-mcp)](https://www.npmjs.com/package/agent-planner-mcp)
+[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
+[![MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-## Overview
+MCP server for [AgentPlanner](https://agentplanner.io) — AI agent orchestration with planning, dependencies, knowledge graphs, and human oversight. Works with Claude Desktop, Claude Code, ChatGPT, Cursor, Windsurf, Cline, and any MCP-compatible client.
 
-This MCP server connects to the Planning System API, providing AI agents with comprehensive planning capabilities through a clean, structured interface. All interactions use JSON responses for easy parsing and processing.
+## Prerequisites
 
-## ✨ Key Features
+- An AgentPlanner account at [agentplanner.io](https://agentplanner.io)
+- An API token (Settings > API Tokens in the AgentPlanner UI)
 
-### Core Capabilities
-- **Full CRUD Operations**: Create, read, update, and delete plans, nodes, and artifacts
-- **Unified Search**: Single powerful search tool for all contexts (global, plans, nodes)
-- **Batch Operations**: Update multiple nodes or retrieve multiple artifacts efficiently
-- **Rich Context**: Get comprehensive node context including ancestry, children, logs, and artifacts
-- **Structured Responses**: Clean JSON data for easy agent processing
+## Setup
 
-### Available Tools
+### Claude Desktop
 
-#### Planning & Search
-- `search` - Universal search across all scopes with filters
-- `create_plan` - Create new plans
-- `update_plan` - Update plan properties
-- `delete_plan` - Delete entire plans
-- `get_plan_structure` - Get hierarchical plan structure
-- `get_plan_summary` - Get comprehensive statistics and summary
-
-#### Node Management
-- `create_node` - Create phases, tasks, or milestones
-- `update_node` - Update any node properties
-- `delete_node` - Delete nodes and their children
-- `move_node` - Reorder or reparent nodes
-- `get_node_context` - Get rich contextual information
-- `get_node_ancestry` - Get path from root to node
-- `batch_update_nodes` - Update multiple nodes at once
-
-#### Collaboration & Tracking
-- `add_log` - Add log entries (including comments, progress, reasoning, etc.)
-- `get_logs` - Retrieve filtered log entries
-- `manage_artifact` - Add, get, search, or list artifacts
-- `batch_get_artifacts` - Retrieve multiple artifacts efficiently
-
-## Getting Started
-
-### Prerequisites
-
-- Node.js 16+
-- npm or yarn
-- Access to a running Planning System API
-- API token for authentication
-
-### Quick Setup (Recommended)
-
-1. Install dependencies
-```bash
-npm install
-```
-
-2. Run the automated setup wizard
-```bash
-npm run setup
-```
-
-The wizard will:
-- Check API server connectivity
-- Guide you through creating an API token in the UI
-- Create your `.env` file
-- Detect and update your Claude Desktop config
-- Test the connection
-
-That's it! Restart Claude Desktop and you're ready to go.
-
-### Manual Installation (Advanced)
-
-If you prefer manual setup or the wizard doesn't work for your setup:
-
-1. Clone the repository
-```bash
-git clone https://github.com/talkingagents/agent-planner-mcp.git
-cd agent-planner-mcp
-```
-
-2. Install dependencies
-```bash
-npm install
-```
-
-3. Create an API token:
-   - Open http://localhost:3001/app/settings in your browser
-   - Navigate to "API Tokens" section
-   - Click "Create MCP Token"
-   - Copy the generated token
-
-4. Create `.env` file:
-```bash
-cp .env.example .env
-```
+Add to your `claude_desktop_config.json`:
 
-Edit the `.env` file:
-```
-API_URL=http://localhost:3000
-USER_API_TOKEN=your_api_token_here
-MCP_SERVER_NAME=planning-system
-MCP_SERVER_VERSION=0.2.0
-NODE_ENV=production
+```json
+{
+  "mcpServers": {
+    "agent-planner": {
+      "command": "npx",
+      "args": ["-y", "agent-planner-mcp"],
+      "env": {
+        "USER_API_TOKEN": "your-token",
+        "API_URL": "https://agentplanner.io/api"
+      }
+    }
+  }
+}
 ```
 
-5. Configure Claude Desktop manually (see "Using with Claude Desktop" section below)
-
-6. Start the server
-```bash
-npm start
-```
+Config location: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) | `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
 
-## Transport Modes
+### Claude Code
 
-The Planning System MCP Server supports two transport modes:
-
-### 🖥️ stdio Mode (Default)
-For **local use** with Claude Desktop, Claude Code, and other local MCP clients:
-- Default transport when running `npm start`
-- Communication via stdin/stdout
-- Best for development and personal use
-- See sections below for Claude Desktop configuration
-
-### 🌐 HTTP/SSE Mode
-For **remote access** via Anthropic's MCP Connector and cloud deployments:
-- Implements MCP Streamable HTTP specification (2025-06-18)
-- RESTful JSON-RPC API over HTTP
-- Production-ready for Cloud Run deployment
-- Supports session management and concurrent connections
-- **Documentation**: See [HTTP_MODE.md](./HTTP_MODE.md)
-- **Deployment**: See [MCP_REGISTRY.md](./MCP_REGISTRY.md)
-
-**Quick Start (HTTP Mode):**
 ```bash
-# Local development
-npm run start:http
-# Server runs on http://127.0.0.1:3100
-
-# Production deployment
-./deploy.sh
-# Deploys to Google Cloud Run (europe-north1)
+claude mcp add agent-planner -- npx -y agent-planner-mcp
 ```
 
-**Use Cases:**
-- ✅ **Anthropic Messages API**: Use with Claude via MCP Connector
-- ✅ **Multi-Agent Systems**: agent-runtime integration
-- ✅ **Cloud Deployment**: Scalable, always-available service
-- ✅ **MCP Registry**: Discoverable via registry lookup
+Then set the env vars `USER_API_TOKEN` and `API_URL=https://agentplanner.io/api`.
 
-For detailed HTTP mode documentation, see [HTTP_MODE.md](./HTTP_MODE.md).
+### ChatGPT
 
-## Using with Claude Desktop
+1. Settings > Apps > Advanced > Developer mode
+2. Add MCP Server > URL: `https://agentplanner.io/mcp`
+3. Auth type: API Key > enter your token from agentplanner.io Settings
 
-### Option 1: Using npx (Recommended - Simplest Setup)
+### Cursor
 
-Add to your `claude_desktop_config.json`:
+Add to `.cursor/mcp.json` in your project root:
 
 ```json
 {
   "mcpServers": {
-    "planning-system": {
+    "agent-planner": {
       "command": "npx",
-      "args": [
-        "-y",
-        "agent-planner-mcp"
-      ],
+      "args": ["-y", "agent-planner-mcp"],
       "env": {
-        "API_URL": "https://api.agentplanner.io",
-        "USER_API_TOKEN": "your_api_token_here"
+        "USER_API_TOKEN": "your-token",
+        "API_URL": "https://agentplanner.io/api"
       }
     }
   }
 }
 ```
 
-**Benefits:**
-- No need to clone the repository
-- Always uses the latest published version
-- Simplest configuration
+### Windsurf
 
-**For local development**, use `http://localhost:3000` instead:
-```json
-"API_URL": "http://localhost:3000"
-```
-
-### Option 2: Using Local Installation
-
-If you prefer to run from a local clone:
+Add to `~/.codeium/windsurf/mcp_config.json`:
 
 ```json
 {
   "mcpServers": {
-    "planning-system": {
-      "command": "node",
-      "args": [
-        "/path/to/agent-planner-mcp/src/index.js"
-      ],
+    "agent-planner": {
+      "command": "npx",
+      "args": ["-y", "agent-planner-mcp"],
       "env": {
-        "API_URL": "https://api.agentplanner.io",
-        "USER_API_TOKEN": "your_api_token_here"
+        "USER_API_TOKEN": "your-token",
+        "API_URL": "https://agentplanner.io/api"
       }
     }
   }
 }
 ```
 
-Then restart Claude Desktop to load the planning tools.
+### Cline (VS Code)
 
-## Example Usage
+Add the same JSON config to your Cline MCP settings in VS Code.
 
-### Search Examples
+### Any HTTP MCP Client
 
-```javascript
-// Global search
-search({ 
-  scope: "global", 
-  query: "API integration",
-  filters: { type: "task", status: "in_progress" }
-})
+- Endpoint: `https://agentplanner.io/mcp`
+- Discovery: `https://agentplanner.io/.well-known/mcp.json`
+- Auth header: `Authorization: ApiKey <your-token>`
+- Transport: Streamable HTTP (MCP 2025-03-26)
 
-// Search within a specific plan
-search({ 
-  scope: "plan", 
-  scope_id: "plan-123",
-  query: "testing"
-})
-```
+## Key Features
 
-### Plan Management
-
-```javascript
-// Create a plan with initial structure
-create_plan({ 
-  title: "Product Launch Q1 2025",
-  description: "Complete product launch plan",
-  status: "active"
-})
-
-// Add nodes to the plan
-create_node({
-  plan_id: "plan-123",
-  node_type: "phase",
-  title: "Market Research",
-  description: "Initial market analysis and competitor research"
-})
-```
+- **60+ tools** for planning, task management, dependencies, and knowledge
+- **Dependency graph** with cycle detection, impact analysis, and critical path
+- **Progressive context** — 4-layer context assembly with token budgeting
+- **Knowledge graph** — temporal knowledge via Graphiti (entities, facts, contradictions)
+- **RPI chains** — Research > Plan > Implement task decomposition
+- **Goal tracking** — health dashboard, briefings, bottleneck detection
+- **Task claims** — TTL-based locking for multi-agent coordination
+- **Organizations** — multi-tenant isolation
 
-### Batch Operations
-
-```javascript
-// Update multiple nodes efficiently
-batch_update_nodes({
-  plan_id: "plan-123",
-  updates: [
-    { node_id: "node-1", status: "completed" },
-    { node_id: "node-2", status: "in_progress" },
-    { node_id: "node-3", description: "Updated requirements" }
-  ]
-})
-
-// Get multiple artifacts at once
-batch_get_artifacts({
-  plan_id: "plan-123",
-  artifact_requests: [
-    { node_id: "node-1", artifact_id: "art-1" },
-    { node_id: "node-2", artifact_id: "art-2" }
-  ]
-})
-```
+## Available Tools
 
-### Rich Context
-
-```javascript
-// Get comprehensive node information
-get_node_context({
-  plan_id: "plan-123",
-  node_id: "node-456"
-})
-// Returns: node details, children, logs, artifacts, plan info
-
-// Track node ancestry
-get_node_ancestry({
-  plan_id: "plan-123",
-  node_id: "node-456"
-})
-// Returns: path from root to node
-```
+### Planning & Search
+- `search` - Universal search across all scopes with filters
+- `create_plan` / `update_plan` / `delete_plan` - Plan CRUD
+- `get_plan_structure` - Hierarchical plan tree
+- `get_plan_summary` - Statistics and summary
 
-## Project Structure
+### Node Management
+- `create_node` / `update_node` / `delete_node` - Node CRUD
+- `move_node` - Reorder or reparent nodes
+- `batch_update_nodes` - Update multiple nodes at once
+- `get_node_context` / `get_node_ancestry` - Rich context
 
-```
-src/
-├── index.js              # Main entry point
-├── tools.js              # Tool implementations
-├── api-client.js         # API client with axios
-└── tools/
-    └── search-wrapper.js # Search functionality wrapper
-```
+### Dependencies & Analysis
+- `create_dependency` / `delete_dependency` - Manage edges
+- `list_dependencies` / `get_node_dependencies` - Query graph
+- `analyze_impact` - Delay/block/remove scenario analysis
+- `get_critical_path` - Longest blocking chain
+- `create_rpi_chain` - Research > Plan > Implement chain
 
-## Development
+### Progressive Context
+- `get_task_context` - Primary context tool (depth 1-4, token budget)
+- `suggest_next_tasks` - Dependency-aware suggestions
+- `get_agent_context` / `get_plan_context` - Focused views
 
-### Running in Development Mode
+### Knowledge Graph
+- `add_learning` / `recall_knowledge` - Learn and retrieve
+- `find_entities` / `check_contradictions` - Graph queries
+- `get_recent_episodes` - Temporal episodes
 
-```bash
-npm run dev  # Auto-restart on changes
-```
+### Goals & Organizations
+- `create_goal` / `update_goal` / `list_goals` / `get_goal` - Goal management
+- `check_goals_health` - Health dashboard
+- `create_organization` / `get_organization` / `list_organizations` / `update_organization`
 
-### Environment Variables
+### Collaboration
+- `add_log` / `get_logs` - Log entries (comments, progress, reasoning)
+- `claim_task` / `release_task` - Task locking
+- `share_plan` - Collaboration management
 
-- `API_URL` - Planning System API URL
-- `USER_API_TOKEN` - Authentication token
-- `MCP_SERVER_NAME` - Server name (default: planning-system-mcp)
-- `MCP_SERVER_VERSION` - Server version (default: 0.2.0)
-- `NODE_ENV` - Environment (development/production)
+## LLM Skill Reference
 
-### Testing Tools
+See **[SKILL.md](./SKILL.md)** for a complete reference designed to be consumed by LLMs. Include it in system prompts or agent configurations to give any LLM full knowledge of how to use AgentPlanner tools effectively.
 
-```javascript
-// Test search functionality
-search({ scope: "global", query: "test" })
+See **[AGENT_GUIDE.md](./AGENT_GUIDE.md)** for a quick reference card.
 
-// Test node operations
-create_node({ plan_id: "...", node_type: "task", title: "Test" })
-update_node({ plan_id: "...", node_id: "...", status: "completed" })
-delete_node({ plan_id: "...", node_id: "..." })
+## Transport Modes
 
-// Test batch operations
-batch_update_nodes({ plan_id: "...", updates: [...] })
+### stdio (default)
+For local use with Claude Desktop, Claude Code, Cursor, Windsurf, Cline:
+```bash
+npx agent-planner-mcp
 ```
 
-## Troubleshooting
+### HTTP/SSE
+For remote access (ChatGPT, cloud deployments, multi-agent systems):
+```bash
+MCP_TRANSPORT=http npx agent-planner-mcp
+# Listens on http://127.0.0.1:3100
+```
 
-### Common Issues
+Production endpoint: `https://agentplanner.io/mcp`
 
-- **Connection errors**: Ensure the Planning System API is running
-- **Authentication errors**: Verify your USER_API_TOKEN is valid
-- **Tool errors**: Check error messages in console output
+See [HTTP_MODE.md](./HTTP_MODE.md) for details.
 
-### Debug Mode
+## Local Development
 
-Enable verbose logging:
 ```bash
-NODE_ENV=development npm start
+git clone https://github.com/TAgents/agent-planner-mcp.git
+cd agent-planner-mcp
+npm install
+npm run setup    # Interactive setup wizard
+npm run dev      # Dev server with hot reload
 ```
 
-## Performance Tips
+### Environment Variables
 
-1. Use batch operations when updating multiple items
-2. Use appropriate search scopes to minimize API calls
-3. Cache plan structures when making multiple operations
-4. Apply filters to limit result sets
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `API_URL` | AgentPlanner API URL | `http://localhost:3000` |
+| `USER_API_TOKEN` | API token (required) | — |
+| `MCP_TRANSPORT` | `stdio` or `http` | `stdio` |
+| `PORT` | HTTP mode port | `3100` |
+| `NODE_ENV` | Environment | `production` |
 
 ## License
 
-MIT License - see LICENSE file for details.
+MIT License - see [LICENSE](./LICENSE) for details.
 
 ## Support
 
-- Report bugs via GitHub Issues
-- See [PDR.md](./PDR.md) for technical design details
-- Check [CHANGELOG.md](./CHANGELOG.md) for version history
+- [GitHub Issues](https://github.com/TAgents/agent-planner-mcp/issues)
+- [CHANGELOG.md](./CHANGELOG.md) for version history
+- [PDR.md](./PDR.md) for technical design