Planning System MCP Server

Instructions

Implementation Reference

• src/tools.js:443-517 (handler)

  Handler for the 'search' MCP tool. Dispatches based on scope to globalSearch or searchPlan wrappers from search-wrapper.js, or client-side filtering for plans. Applies additional filters and formats response using formatResponse.
  if (name === "search") { const { scope, scope_id, query, filters = {} } = args; let results = []; switch (scope) { case "global": // Global search across all plans const searchWrapper = require('./tools/search-wrapper'); results = await searchWrapper.globalSearch(query); break; case "plans": // Search only in plan titles/descriptions const plans = await apiClient.plans.getPlans(); // Handle wildcard queries if (query === '*' || query === '' || !query) { // Return all plans (with optional status filter) results = plans.filter(plan => !filters.status || plan.status === filters.status ); } else { // Normal search const queryLower = query.toLowerCase(); results = plans.filter(plan => { const titleMatch = plan.title.toLowerCase().includes(queryLower); const descMatch = plan.description?.toLowerCase().includes(queryLower); const statusMatch = !filters.status || plan.status === filters.status; return (titleMatch || descMatch) && statusMatch; }); } break; case "plan": // Search within a specific plan if (!scope_id) { throw new Error("scope_id (plan_id) is required when scope is 'plan'"); } const searchWrapperPlan = require('./tools/search-wrapper'); results = await searchWrapperPlan.searchPlan(scope_id, query); break; case "node": // Search within a specific node's children if (!scope_id) { throw new Error("scope_id (node_id) is required when scope is 'node'"); } // This would need a specific implementation results = []; break; default: // Default to global search const searchWrapperDefault = require('./tools/search-wrapper'); results = await searchWrapperDefault.globalSearch(query); } // Apply filters if (filters.type) { results = results.filter(item => item.type === filters.type); } if (filters.limit) { results = results.slice(0, filters.limit); } return formatResponse({ query, scope, scope_id, filters, count: results.length, results }); }
• src/tools.js:61-104 (schema)

  Schema definition for the 'search' tool, defining input parameters: scope (global/plans/plan/node), scope_id, query (required), and optional filters (status, type, limit).
  name: "search", description: "Universal search tool for plans, nodes, and content", inputSchema: { type: "object", properties: { scope: { type: "string", description: "Search scope", enum: ["global", "plans", "plan", "node"], default: "global" }, scope_id: { type: "string", description: "Plan ID (if scope is 'plan') or Node ID (if scope is 'node')" }, query: { type: "string", description: "Search query" }, filters: { type: "object", description: "Optional filters", properties: { status: { type: "string", description: "Filter by status", enum: ["draft", "active", "completed", "archived", "not_started", "in_progress", "blocked"] }, type: { type: "string", description: "Filter by type", enum: ["plan", "node", "phase", "task", "milestone", "artifact", "log"] }, limit: { type: "integer", description: "Maximum number of results", default: 20 } } } }, required: ["query"] } },
• src/index.js:4-54 (registration)

  Registers the MCP tools on the server instance by calling setupTools(server), which includes the 'search' tool.
  const { setupTools } = require('./tools'); require('dotenv').config(); /** * Initialize the Planning System MCP Server * * Features: * - Simplified architecture with tools-only interface * - Full CRUD operations on all entities * - Unified search across all scopes * - Batch operations for efficiency * - Structured JSON responses * - Comprehensive logging system */ async function main() { const isDev = process.env.NODE_ENV === 'development'; if (isDev) { console.error('Initializing Planning System MCP Server...'); } 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'}`); // 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);
• src/tools/search-wrapper.js:17-71 (helper)

  Helper function searchPlan that wraps apiClient.search.searchPlan, normalizes response to return results array directly.
  async function searchPlan(planId, query) { try { // Call the original search function from the API client const response = await apiClient.search.searchPlan(planId, query); // Log the actual response for debugging if (process.env.NODE_ENV === 'development') { console.log('Search plan response:', typeof response, Object.keys(response || {})); } // Handle different response formats if (!response) { return []; } // If response is already an array, return it if (Array.isArray(response)) { return response; } // If response has results array if (response.results && Array.isArray(response.results)) { return response.results; } // If response has other properties that are arrays const results = []; Object.keys(response).forEach(key => { if (Array.isArray(response[key])) { response[key].forEach(item => { results.push({ ...item, type: item.type || key, source: 'plan_search' }); }); } }); if (results.length > 0) { return results; } // Try to parse response as a search result object if (response.query !== undefined && response.count !== undefined) { return response.results || []; } console.error('Unexpected search response format:', JSON.stringify(response).substring(0, 200)); return []; } catch (error) { console.error('Error in searchPlan wrapper:', error.message); return []; } }
• src/tools/search-wrapper.js:79-182 (helper)

  Helper function globalSearch that wraps apiClient.search.globalSearch, handles various response formats, flattens and enriches results with type, category, source.
  async function globalSearch(query) { try { // Call the original global search function const response = await apiClient.search.globalSearch(query); if (process.env.NODE_ENV === 'development') { console.log('Global search response type:', typeof response); if (response) { console.log('Response keys:', Object.keys(response)); } } // Handle different response formats if (!response) { return []; } // If response is already an array of results if (Array.isArray(response)) { return response.map(item => ({ ...item, type: item.type || 'unknown', source: 'global_search' })); } // If response has a results property if (response.results !== undefined) { // If results is already an array, return it if (Array.isArray(response.results)) { return response.results.map(item => ({ ...item, type: item.type || 'unknown', source: 'global_search' })); } // If results is an object with categories if (typeof response.results === 'object') { const allResults = []; // Collect results from each category (plans, nodes, comments, etc.) Object.keys(response.results).forEach(category => { if (Array.isArray(response.results[category])) { // Add category type to each result const categoryResults = response.results[category].map(item => ({ ...item, type: item.type || category, category, source: 'global_search' })); allResults.push(...categoryResults); } }); return allResults; } } // Check if response has categorized results (plans, nodes, etc.) const categories = ['plans', 'nodes', 'comments', 'logs', 'artifacts']; const allResults = []; categories.forEach(category => { if (response[category] && Array.isArray(response[category])) { response[category].forEach(item => { allResults.push({ ...item, type: item.type || category.slice(0, -1), // Remove 's' from category category, source: 'global_search' }); }); } }); if (allResults.length > 0) { return allResults; } // Generic handler for any object with arrays Object.keys(response).forEach(key => { if (Array.isArray(response[key]) && key !== 'results') { response[key].forEach(item => { allResults.push({ ...item, type: item.type || key, category: key, source: 'global_search' }); }); } }); return allResults; } catch (error) { console.error('Error in globalSearch wrapper:', error.message); if (error.response) { console.error('API error status:', error.response.status); console.error('API error data:', error.response.data); } return []; } }