agent-planner-mcp 0.3.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Talking Agents Oy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -112,6 +112,45 @@ NODE_ENV=production
 npm start
 ```
 
+## Transport Modes
+
+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)
+```
+
+**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
+
+For detailed HTTP mode documentation, see [HTTP_MODE.md](./HTTP_MODE.md).
+
 ## Using with Claude Desktop
 
 ### Option 1: Using npx (Recommended - Simplest Setup)

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "agent-planner-mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "MCP server interface for the Planning System API",
   "main": "src/index.js",
   "bin": {
-    "agent-planner-mcp": "src/index.js"
+    "agent-planner-mcp": "src/cli.js"
   },
   "scripts": {
     "start": "node src/index.js",
+    "start:http": "MCP_TRANSPORT=http node src/index.js",
     "dev": "nodemon src/index.js",
+    "dev:http": "MCP_TRANSPORT=http nodemon src/index.js",
     "test": "jest",
     "test:tools": "node test-tools.js",
     "setup": "node src/setup.js",
@@ -27,7 +29,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/talkingagents/agent-planner-mcp.git"
+    "url": "git+https://github.com/TAgents/agent-planner-mcp.git"
   },
   "homepage": "https://agentplanner.io",
   "bugs": {
@@ -37,12 +39,16 @@
     "@modelcontextprotocol/sdk": "^1.8.0",
     "axios": "^1.6.2",
     "dotenv": "^16.3.1",
+    "express": "^4.18.2",
     "ignore": "^7.0.3"
   },
   "devDependencies": {
     "jest": "^29.7.0",
     "nodemon": "^3.0.1"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "engines": {
     "node": ">=16.0.0"
   },

package/src/api-client.js

@@ -26,23 +26,28 @@ const apiClient = axios.create({
   }
 });
 
-// Log API requests in debug mode
-apiClient.interceptors.request.use(request => {
-  console.error(`API Request: ${request.method.toUpperCase()} ${request.url}`);
-  return request;
-});
-
-// Log API responses in debug mode
+// Log API requests only in development mode
+if (process.env.NODE_ENV === 'development') {
+  apiClient.interceptors.request.use(request => {
+    console.error(`API Request: ${request.method.toUpperCase()} ${request.url}`);
+    return request;
+  });
+}
+
+// Handle API responses - log details only in development, always handle auth errors helpfully
 apiClient.interceptors.response.use(
   response => {
-    console.error(`API Response: ${response.status} ${response.statusText}`);
+    if (process.env.NODE_ENV === 'development') {
+      console.error(`API Response: ${response.status} ${response.statusText}`);
+    }
     return response;
   },
   error => {
+    // Always log auth errors helpfully (but not the token itself)
     if (error.response && error.response.status === 401) {
-      console.error('API Error: Authentication failed (401). Please check that your USER_API_TOKEN is correct, valid, and not revoked.');
-      console.error('If you are still using the old API_TOKEN, please generate a USER_API_TOKEN from the agent-planner UI.');
-    } else {
+      console.error('API Error: Authentication failed (401). Please check that your USER_API_TOKEN is correct and not revoked.');
+    } else if (process.env.NODE_ENV === 'development') {
+      // Only log other errors in development
       console.error('API Error:', error.response ? error.response.data : error.message);
     }
     return Promise.reject(error);
@@ -100,6 +105,30 @@ const plans = {
    */
   deletePlan: async (planId) => {
     await apiClient.delete(`/plans/${planId}`);
+  },
+
+  /**
+   * Update plan visibility (make public or private)
+   * @param {string} planId - Plan ID
+   * @param {Object} visibilityData - Visibility settings
+   * @param {string} visibilityData.visibility - 'public' or 'private'
+   * @param {string} [visibilityData.github_repo_owner] - GitHub repo owner (for public plans)
+   * @param {string} [visibilityData.github_repo_name] - GitHub repo name (for public plans)
+   * @returns {Promise<Object>} - Updated plan with visibility info
+   */
+  updateVisibility: async (planId, visibilityData) => {
+    const response = await apiClient.put(`/plans/${planId}/visibility`, visibilityData);
+    return response.data;
+  },
+
+  /**
+   * Get a public plan (no authentication required in browser, but API token needed for MCP)
+   * @param {string} planId - Plan ID
+   * @returns {Promise<Object>} - Public plan details
+   */
+  getPublicPlan: async (planId) => {
+    const response = await apiClient.get(`/plans/${planId}/public`);
+    return response.data;
   }
 };
 
@@ -110,10 +139,18 @@ const nodes = {
   /**
    * Get nodes for a plan
    * @param {string} planId - Plan ID
+   * @param {Object} options - Optional query parameters
+   * @param {boolean} options.include_details - Include full node details (default: false)
    * @returns {Promise<Array>} - List of nodes
    */
-  getNodes: async (planId) => {
-    const response = await apiClient.get(`/plans/${planId}/nodes`);
+  getNodes: async (planId, options = {}) => {
+    const params = new URLSearchParams();
+    if (options.include_details) {
+      params.append('include_details', 'true');
+    }
+
+    const queryString = params.toString() ? `?${params.toString()}` : '';
+    const response = await apiClient.get(`/plans/${planId}/nodes${queryString}`);
     return response.data;
   },
 
@@ -230,101 +267,6 @@ const logs = {
   }
 };
 
-/**
- * Artifact-related API functions
- */
-const artifacts = {
-  /**
-   * Get artifacts for a node
-   * @param {string} planId - Plan ID
-   * @param {string} nodeId - Node ID
-   * @returns {Promise<Array>} - List of artifacts
-   */
-  getArtifacts: async (planId, nodeId) => {
-    const response = await apiClient.get(`/plans/${planId}/nodes/${nodeId}/artifacts`);
-    return response.data;
-  },
-
-  /**
-   * Get a specific artifact by ID
-   * @param {string} planId - Plan ID
-   * @param {string} nodeId - Node ID
-   * @param {string} artifactId - Artifact ID
-   * @returns {Promise<Object>} - Artifact details
-   */
-  getArtifact: async (planId, nodeId, artifactId) => {
-    const response = await apiClient.get(`/plans/${planId}/nodes/${nodeId}/artifacts/${artifactId}`);
-    return response.data;
-  },
-
-  /**
-   * Get the content of an artifact
-   * @param {string} planId - Plan ID
-   * @param {string} nodeId - Node ID
-   * @param {string} artifactId - Artifact ID
-   * @returns {Promise<string>} - Artifact content
-   */
-  getArtifactContent: async (planId, nodeId, artifactId) => {
-    try {
-      // First, get artifact details to check the URL
-      const artifact = await artifacts.getArtifact(planId, nodeId, artifactId);
-      
-      // If the artifact has a URL, fetch the content
-      if (artifact.url) {
-        try {
-          // For local file paths, use fs instead of HTTP request
-          if (artifact.url.startsWith('/') && !artifact.url.startsWith('/api/')) {
-            const fs = require('fs').promises;
-            try {
-              // Read the file directly from the filesystem
-              const content = await fs.readFile(artifact.url, 'utf8');
-              return content;
-            } catch (fsError) {
-              console.error('Error reading artifact file:', fsError);
-              throw new Error(`Cannot read file at ${artifact.url}: ${fsError.message}`);
-            }
-          } else {
-            // For internal URLs (API routes), append to base URL
-            const contentUrl = artifact.url.startsWith('/api/') 
-              ? `${apiClient.defaults.baseURL}${artifact.url}`
-              : artifact.url;
-            
-            const contentResponse = await axios.get(contentUrl, {
-              headers: {
-                'Authorization': apiClient.defaults.headers['Authorization'],
-                'Accept': artifact.content_type || 'text/plain'
-              },
-              responseType: 'text'
-            });
-            
-            return contentResponse.data;
-          }
-        } catch (fetchError) {
-          console.error('Error fetching artifact content:', fetchError);
-          throw new Error(`Failed to fetch artifact content: ${fetchError.message}`);
-        }
-      } else {
-        throw new Error('Artifact does not have a content URL');
-      }
-    } catch (error) {
-      console.error('Error fetching artifact content:', error);
-      throw error;
-    }
-  },
-
-  /**
-   * Add an artifact to a node
-   * @param {string} planId - Plan ID
-   * @param {string} nodeId - Node ID
-   * @param {Object} artifactData - Artifact data
-   * @returns {Promise<Object>} - Created artifact
-   */
-  addArtifact: async (planId, nodeId, artifactData) => {
-    const response = await apiClient.post(`/plans/${planId}/nodes/${nodeId}/artifacts`, artifactData);
-    return response.data;
-  }
-};
-
 /**
  * Activity-related API functions
  */
@@ -335,7 +277,7 @@ const activity = {
    * @returns {Promise<Array>} - Activity feed
    */
   getPlanActivity: async (planId) => {
-    const response = await apiClient.get(`/activity/plan/${planId}`);
+    const response = await apiClient.get(`/activity/plans/${planId}/activity`);
     return response.data;
   },
 
@@ -344,7 +286,7 @@ const activity = {
    * @returns {Promise<Array>} - Activity feed
    */
   getGlobalActivity: async () => {
-    const response = await apiClient.get('/activity');
+    const response = await apiClient.get('/activity/feed');
     return response.data;
   }
 };
@@ -499,7 +441,7 @@ const tokens = {
    * @returns {Promise<Array>} - List of API tokens
    */
   getTokens: async () => {
-    const response = await apiClient.get('/tokens');
+    const response = await apiClient.get('/auth/token');
     return response.data;
   },
 
@@ -509,7 +451,7 @@ const tokens = {
    * @returns {Promise<Object>} - Created token
    */
   createToken: async (tokenData) => {
-    const response = await apiClient.post('/tokens', tokenData);
+    const response = await apiClient.post('/auth/token', tokenData);
     return response.data;
   },
 
@@ -519,7 +461,221 @@ const tokens = {
    * @returns {Promise<void>}
    */
   revokeToken: async (tokenId) => {
-    await apiClient.delete(`/tokens/${tokenId}`);
+    await apiClient.delete(`/auth/token/${tokenId}`);
+  }
+};
+
+/**
+ * Organization API functions
+ */
+const organizations = {
+  list: async () => {
+    const response = await apiClient.get('/organizations');
+    return response.data.organizations || response.data;
+  },
+  
+  get: async (orgId) => {
+    const response = await apiClient.get(`/organizations/${orgId}`);
+    return response.data;
+  },
+  
+  create: async (data) => {
+    const response = await apiClient.post('/organizations', data);
+    return response.data;
+  },
+  
+  update: async (orgId, data) => {
+    const response = await apiClient.put(`/organizations/${orgId}`, data);
+    return response.data;
+  },
+  
+  delete: async (orgId) => {
+    const response = await apiClient.delete(`/organizations/${orgId}`);
+    return response.data;
+  },
+  
+  listMembers: async (orgId) => {
+    const response = await apiClient.get(`/organizations/${orgId}/members`);
+    return response.data.members || response.data;
+  },
+  
+  addMember: async (orgId, data) => {
+    const response = await apiClient.post(`/organizations/${orgId}/members`, data);
+    return response.data;
+  },
+  
+  removeMember: async (orgId, memberId) => {
+    const response = await apiClient.delete(`/organizations/${orgId}/members/${memberId}`);
+    return response.data;
+  }
+};
+
+/**
+ * Goals API functions
+ */
+const goals = {
+  list: async (filters = {}) => {
+    const params = new URLSearchParams();
+    if (filters.organization_id) params.append('organization_id', filters.organization_id);
+    if (filters.status) params.append('status', filters.status);
+    const response = await apiClient.get(`/goals?${params.toString()}`);
+    return response.data.goals || response.data;
+  },
+  
+  get: async (goalId) => {
+    const response = await apiClient.get(`/goals/${goalId}`);
+    return response.data;
+  },
+  
+  create: async (data) => {
+    const response = await apiClient.post('/goals', data);
+    return response.data;
+  },
+  
+  update: async (goalId, data) => {
+    const response = await apiClient.put(`/goals/${goalId}`, data);
+    return response.data;
+  },
+  
+  updateMetrics: async (goalId, metrics) => {
+    const response = await apiClient.put(`/goals/${goalId}/metrics`, { metrics });
+    return response.data;
+  },
+  
+  delete: async (goalId) => {
+    const response = await apiClient.delete(`/goals/${goalId}`);
+    return response.data;
+  },
+  
+  linkPlan: async (goalId, planId) => {
+    const response = await apiClient.post(`/goals/${goalId}/plans/${planId}`);
+    return response.data;
+  },
+  
+  unlinkPlan: async (goalId, planId) => {
+    const response = await apiClient.delete(`/goals/${goalId}/plans/${planId}`);
+    return response.data;
+  }
+};
+
+/**
+ * Knowledge Store API functions
+ */
+const knowledge = {
+  /**
+   * List knowledge entries with optional filters
+   * GET /knowledge
+   */
+  listEntries: async (storeIdOrFilters, filters = {}) => {
+    const params = new URLSearchParams();
+    // Support both (storeId, filters) and (filters) calling patterns
+    if (typeof storeIdOrFilters === 'string') {
+      params.append('scopeId', storeIdOrFilters);
+      if (filters.entry_type) params.append('entryType', filters.entry_type);
+      if (filters.tags) params.append('tags', filters.tags);
+      if (filters.limit) params.append('limit', filters.limit);
+      if (filters.offset) params.append('offset', filters.offset);
+    } else if (typeof storeIdOrFilters === 'object') {
+      const f = storeIdOrFilters;
+      if (f.scope) params.append('scope', f.scope);
+      if (f.scope_id) params.append('scopeId', f.scope_id);
+      if (f.entry_type) params.append('entryType', f.entry_type);
+      if (f.limit) params.append('limit', f.limit);
+      if (f.offset) params.append('offset', f.offset);
+    }
+    const response = await apiClient.get(`/knowledge?${params.toString()}`);
+    return response.data;
+  },
+
+  /**
+   * Alias for listEntries — used by get_context and understand_context tools
+   */
+  getEntries: async (filters = {}) => {
+    return knowledge.listEntries(filters);
+  },
+
+  /**
+   * Get a single knowledge entry
+   * GET /knowledge/:id
+   */
+  getEntry: async (entryId) => {
+    const response = await apiClient.get(`/knowledge/${entryId}`);
+    return response.data;
+  },
+
+  /**
+   * Create a knowledge entry
+   * POST /knowledge
+   */
+  createEntry: async (data) => {
+    const response = await apiClient.post('/knowledge', data);
+    return response.data;
+  },
+
+  /**
+   * Update a knowledge entry
+   * PUT /knowledge/:id
+   */
+  updateEntry: async (entryId, data) => {
+    const response = await apiClient.put(`/knowledge/${entryId}`, data);
+    return response.data;
+  },
+
+  /**
+   * Delete a knowledge entry
+   * DELETE /knowledge/:id
+   */
+  deleteEntry: async (entryId) => {
+    const response = await apiClient.delete(`/knowledge/${entryId}`);
+    return response.data;
+  },
+
+  /**
+   * Semantic search across knowledge entries
+   * POST /knowledge/search
+   */
+  search: async (data) => {
+    const response = await apiClient.post('/knowledge/search', data);
+    return response.data;
+  }
+};
+
+/**
+ * Agent Context API functions (leaf-up context loading)
+ */
+const context = {
+  /**
+   * Get focused context for a specific node (task/phase)
+   * Traverses from node up to root, including goals, org, and knowledge
+   * @param {string} nodeId - Node ID
+   * @param {Object} options - Options (include_knowledge, include_siblings)
+   * @returns {Promise<Object>} - Agent context
+   */
+  getNodeContext: async (nodeId, options = {}) => {
+    const params = new URLSearchParams({ node_id: nodeId });
+    if (options.include_knowledge !== undefined) {
+      params.append('include_knowledge', options.include_knowledge);
+    }
+    if (options.include_siblings !== undefined) {
+      params.append('include_siblings', options.include_siblings);
+    }
+    const response = await apiClient.get(`/context?${params.toString()}`);
+    return response.data;
+  },
+
+  /**
+   * Get plan-level context (overview, not full tree)
+   * @param {string} planId - Plan ID
+   * @param {Object} options - Options (include_knowledge)
+   * @returns {Promise<Object>} - Plan context
+   */
+  getPlanContext: async (planId, options = {}) => {
+    const params = new URLSearchParams({ plan_id: planId });
+    if (options.include_knowledge !== undefined) {
+      params.append('include_knowledge', options.include_knowledge);
+    }
+    const response = await apiClient.get(`/context/plan?${params.toString()}`);
+    return response.data;
   }
 };
 
@@ -532,9 +688,12 @@ module.exports = {
   nodes,
   comments,
   logs,
-  artifacts,
   activity,
   search,
   tokens,
+  organizations,
+  goals,
+  knowledge,
+  context,
   axiosInstance  // Export for direct API calls
 };

package/src/cli.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+/**
+ * CLI Entry Point for agent-planner-mcp
+ * Routes to different commands or starts the MCP server
+ */
+
+const path = require('path');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+// Route to different commands
+switch (command) {
+  case 'setup-claude-code':
+    // Run the setup-claude-code script
+    const setupClaudeCode = require('./setup-claude-code.js');
+    setupClaudeCode.main();
+    break;
+
+  case 'setup':
+    // Run the interactive setup wizard
+    require('./setup.js');
+    break;
+
+  case '--help':
+  case '-h':
+  case 'help':
+    console.log(`
+Agent Planner MCP - Model Context Protocol Server
+
+Usage:
+  npx agent-planner-mcp                    Start MCP server (requires USER_API_TOKEN)
+  npx agent-planner-mcp setup-claude-code  Install orchestration commands to .claude/
+  npx agent-planner-mcp setup              Interactive setup wizard
+  npx agent-planner-mcp --help             Show this help message
+
+Environment Variables:
+  API_URL          - Agent Planner API URL (default: http://localhost:3000)
+  USER_API_TOKEN   - API token from Agent Planner UI (required for server)
+  MCP_SERVER_NAME  - Server name (default: planning-system-mcp)
+  NODE_ENV         - Environment (development/production)
+
+Documentation:
+  https://github.com/talkingagents/agent-planner-mcp
+`);
+    break;
+
+  case '--version':
+  case '-v':
+    const pkg = require('../package.json');
+    console.log(`agent-planner-mcp v${pkg.version}`);
+    break;
+
+  default:
+    // No command or unknown command - start MCP server
+    if (command && !command.startsWith('-')) {
+      console.error(`Unknown command: ${command}`);
+      console.error('Run "npx agent-planner-mcp --help" for usage information.');
+      process.exit(1);
+    }
+    // Start the MCP server
+    require('./index.js');
+}