agent-planner-mcp 0.3.1 → 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,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "MCP server interface for the Planning System API",
   "main": "src/index.js",
   "bin": {
@@ -8,7 +8,9 @@
   },
   "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": "git+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/index.js

@@ -1,12 +1,19 @@
 #!/usr/bin/env node
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { MCPHTTPServer } = require('./server-http');
 const { setupTools } = require('./tools');
 require('dotenv').config();
 
 /**
  * Initialize the Planning System MCP Server
- * 
+ *
+ * Supports two transport modes:
+ * - stdio: For local use with Claude Desktop, Claude Code, etc.
+ * - http: For remote access via Anthropic's MCP Connector
+ *
+ * Set MCP_TRANSPORT=http to use HTTP mode
+ *
  * Features:
  * - Simplified architecture with tools-only interface
  * - Full CRUD operations on all entities
@@ -17,47 +24,72 @@ require('dotenv').config();
  */
 async function main() {
   const isDev = process.env.NODE_ENV === 'development';
-  
+  const transport = process.env.MCP_TRANSPORT || 'stdio';
+
   if (isDev) {
     console.error('Initializing Planning System MCP Server...');
+    console.error(`Transport mode: ${transport}`);
   }
-  
+
   try {
     // Log environment settings
     console.error(`API URL: ${process.env.API_URL || 'http://localhost:3000'}`);
-    
+
     // Check for token
     const userApiToken = process.env.USER_API_TOKEN || process.env.API_TOKEN;
     console.error(`User API Token: ${userApiToken ? '***' + userApiToken.slice(-4) : 'NOT SET'}`);
     console.error(`MCP Server Name: ${process.env.MCP_SERVER_NAME || 'planning-system-mcp'}`);
-    console.error(`MCP Server Version: ${process.env.MCP_SERVER_VERSION || '0.2.0'}`);
-    
+    console.error(`MCP Server Version: ${process.env.MCP_SERVER_VERSION || '0.3.1'}`);
+
     // Validate required environment variables
     if (!userApiToken) {
       throw new Error('USER_API_TOKEN environment variable is required. Please generate one from the Agent Planner UI and set it in .env file.');
     }
-    
-    // Create MCP server instance
-    const server = new Server({
-      name: process.env.MCP_SERVER_NAME || "planning-system-mcp",
-      version: process.env.MCP_SERVER_VERSION || "0.2.0"
-    }, {
-      capabilities: {
-        tools: {}
-      }
-    });
 
-    console.error('MCP Server created');
-    
-    // Setup tools
-    setupTools(server);
-    
-    // Connect transport
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    
-    console.error('MCP Server running on stdio transport');
-    console.error('Ready to accept connections from agents');
+    if (transport === 'http') {
+      // HTTP/SSE transport mode
+      const httpServer = new MCPHTTPServer({
+        port: process.env.PORT || 3100,
+        host: process.env.HOST || '127.0.0.1'
+      });
+
+      await httpServer.start();
+
+      // Handle graceful shutdown
+      process.on('SIGINT', async () => {
+        console.error('\nShutting down MCP HTTP Server...');
+        await httpServer.stop();
+        process.exit(0);
+      });
+
+      process.on('SIGTERM', async () => {
+        console.error('\nShutting down MCP HTTP Server...');
+        await httpServer.stop();
+        process.exit(0);
+      });
+    } else {
+      // Stdio transport mode (default)
+      const server = new Server({
+        name: process.env.MCP_SERVER_NAME || "planning-system-mcp",
+        version: process.env.MCP_SERVER_VERSION || "0.3.1"
+      }, {
+        capabilities: {
+          tools: {}
+        }
+      });
+
+      console.error('MCP Server created');
+
+      // Setup tools
+      setupTools(server);
+
+      // Connect transport
+      const stdioTransport = new StdioServerTransport();
+      await server.connect(stdioTransport);
+
+      console.error('MCP Server running on stdio transport');
+      console.error('Ready to accept connections from agents');
+    }
   } catch (error) {
     console.error('Failed to initialize MCP server:', error);
     process.exit(1);