MeshSeeks

Instructions

Implementation Reference

• src/server.ts:458-567 (handler)

  MCP tool handler for 'convert_task_markdown'. Extracts parameters, executes task_converter.py Python script via spawnAsync, processes output/errors, returns JSON tasks or error.
  if (toolName === 'convert_task_markdown') { const toolArguments = args.params.arguments; // Extract markdownPath (required) let markdownPath: string; if ( toolArguments && typeof toolArguments === 'object' && 'markdownPath' in toolArguments && typeof toolArguments.markdownPath === 'string' ) { markdownPath = toolArguments.markdownPath; } else { throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid required parameter: markdownPath for convert_task_markdown tool'); } // Extract outputPath (optional) let outputPath: string | undefined; if (toolArguments.outputPath && typeof toolArguments.outputPath === 'string') { outputPath = toolArguments.outputPath; } debugLog(`[Debug] Converting markdown task file: ${markdownPath}`); let stderr = ''; try { // Prepare command to run task_converter.py const pythonPath = 'python3'; const converterPath = pathResolve(__dirname, '../docs/task_converter.py'); // Use --json-output flag to get JSON to stdout const args = ['--json-output', markdownPath]; const result = await spawnAsync(pythonPath, [converterPath, ...args], { cwd: homedir(), timeout: 30000 // 30 seconds timeout }); const stdout = result.stdout; stderr = result.stderr; // Extract progress messages and actual errors const stderrLines = stderr.split('\n'); const progressMessages = stderrLines.filter(line => line.includes('[Progress]')); const errorMessages = stderrLines.filter(line => !line.includes('[Progress]') && line.trim()); // Log progress messages progressMessages.forEach(msg => { console.error(msg); // Send to client debugLog(msg); }); if (errorMessages.length > 0) { stderr = errorMessages.join('\n'); debugLog(`[Debug] Task converter stderr: ${stderr}`); } // Check if there was an error from the converter if (stderr && stderr.includes('Markdown format validation failed')) { // Return validation error as a structured response const validationError = { status: 'error', error: 'Markdown format validation failed', details: stderr, helpUrl: 'https://github.com/grahama1970/claude-code-mcp/blob/main/README.md#markdown-task-file-format' }; this.activeRequests.delete(requestId); return { content: [{ type: 'text', text: JSON.stringify(validationError, null, 2) }] }; } // Parse the JSON output const tasks = JSON.parse(stdout); // If outputPath is provided, also save to file if (outputPath) { await fs.writeFile(outputPath, JSON.stringify(tasks, null, 2)); debugLog(`[Debug] Saved converted tasks to: ${outputPath}`); } // Return the converted tasks const response = { status: 'success', tasksCount: tasks.length, outputPath: outputPath || 'none', tasks: tasks }; this.activeRequests.delete(requestId); return { content: [{ type: 'text', text: JSON.stringify(response, null, 2) }] }; } catch (error) { this.activeRequests.delete(requestId); const errorMessage = error instanceof Error ? error.message : String(error); // Check if this is a JSON parsing error (indicating validation failure) if (errorMessage.includes('JSON') && stderr) { const validationError = { status: 'error', error: 'Task conversion failed', details: stderr || errorMessage, helpUrl: 'https://github.com/grahama1970/claude-code-mcp/blob/main/README.md#markdown-task-file-format' }; return { content: [{ type: 'text', text: JSON.stringify(validationError, null, 2) }] }; } throw new McpError(ErrorCode.InternalError, `Failed to convert markdown tasks: ${errorMessage}`); } }
• src/server.ts:299-316 (registration)

  Registers the 'convert_task_markdown' tool in the ListTools response, including description and input schema.
  { name: 'convert_task_markdown', description: 'Converts markdown task files into Claude Code MCP-compatible JSON format. Returns an array of tasks that can be executed using the claude_code tool.', inputSchema: { type: 'object', properties: { markdownPath: { type: 'string', description: 'Path to the markdown task file to convert.', }, outputPath: { type: 'string', description: 'Optional path where to save the JSON output. If not provided, returns the JSON directly.', }, }, required: ['markdownPath'], }, },
• src/server.ts:302-315 (schema)

  Input schema definition for the convert_task_markdown tool, specifying markdownPath as required and outputPath as optional.
  inputSchema: { type: 'object', properties: { markdownPath: { type: 'string', description: 'Path to the markdown task file to convert.', }, outputPath: { type: 'string', description: 'Optional path where to save the JSON output. If not provided, returns the JSON directly.', }, }, required: ['markdownPath'], },
• docs/task_converter.py:260-349 (helper)

  Core helper function that parses markdown task file, validates structure, extracts sections (title, objective, requirements, validation tasks), builds prompts using build_validation_prompt, and formats into MCP-compatible task list.
  def process_markdown(input_file: str, progress_callback: Optional[callable] = None) -> List[Dict[str, Any]]: """ Process a markdown file and extract validation tasks. Args: input_file: Path to the markdown file progress_callback: Optional callback for progress updates Returns: List of tasks in Claude Code MCP format Raises: ValueError: If markdown format is invalid or missing required sections """ if progress_callback: progress_callback("Loading task file...") md = load_file(input_file) if progress_callback: progress_callback("Validating markdown structure...") # Validate markdown structure validation_errors = [] # Extract and validate title title = extract_title(md) if title == "Untitled Task": validation_errors.append("Missing required title. Format: '# Task NNN: Title'") # Extract and validate objective objective = extract_objective(md) if not objective: validation_errors.append("Missing required 'Objective' section. Format: '## Objective\\nDescription'") # Extract and validate requirements requirements = extract_requirements(md) if not requirements: validation_errors.append("Missing or empty 'Requirements' section. Format: '## Requirements\\n1. [ ] Requirement'") # Extract and validate tasks validation_tasks = extract_validation_tasks(md) if not validation_tasks: validation_errors.append("No validation tasks found. Format: '- [ ] Validate `module.py`' with indented steps") # Check for task steps empty_tasks = [] for module, block in validation_tasks: steps = extract_steps(block) if not steps: empty_tasks.append(module) if empty_tasks: validation_errors.append(f"Tasks without steps: {', '.join(empty_tasks)}. Each task needs indented steps") # If there are validation errors, raise exception with helpful message if validation_errors: error_msg = "Markdown format validation failed:\n" error_msg += "\n".join(f" - {error}" for error in validation_errors) error_msg += "\n\nRequired markdown format:\n" error_msg += "# Task NNN: Title\n" error_msg += "## Objective\n" error_msg += "Clear description\n" error_msg += "## Requirements\n" error_msg += "1. [ ] First requirement\n" error_msg += "## Task Section\n" error_msg += "- [ ] Validate `file.py`\n" error_msg += " - [ ] Step 1\n" error_msg += " - [ ] Step 2\n" raise ValueError(error_msg) if progress_callback: progress_callback(f"Converting {len(validation_tasks)} validation tasks...") prompts = [] for i, (module, block) in enumerate(validation_tasks, 1): if progress_callback: progress_callback(f"Task {i}/{len(validation_tasks)}: Converting {module}") steps = extract_steps(block) if not steps: continue # skip if no steps found (already reported in validation) prompt = build_validation_prompt(title, objective, module, steps, requirements) prompts.append(prompt) if progress_callback: progress_callback("Conversion complete!") return format_tasks_for_mcp(prompts)
• docs/task_converter.py:545-603 (helper)

  Entry point for the task_converter.py script. Handles --json-output mode for MCP integration by calling process_markdown and printing JSON to stdout, with progress to stderr.
  def main(): """Main function to execute the script from command line.""" # Check for --json-output flag for MCP integration json_output_mode = '--json-output' in sys.argv if json_output_mode: # Remove the flag from argv for processing sys.argv.remove('--json-output') # Expect only input file if len(sys.argv) != 2: print("Usage: python task_converter.py --json-output <input_markdown>", file=sys.stderr) sys.exit(1) input_file = sys.argv[1] # Validate input file if not os.path.isfile(input_file): print(f"Error: Input file '{input_file}' does not exist.", file=sys.stderr) sys.exit(1) try: # Process markdown and output JSON to stdout def progress_to_stderr(msg): print(f"[Progress] {msg}", file=sys.stderr) tasks = process_markdown(input_file, progress_callback=progress_to_stderr) # Output JSON to stdout for MCP consumption print(json.dumps(tasks, indent=2)) sys.exit(0) except Exception as e: print(f"Error during conversion: {str(e)}", file=sys.stderr) sys.exit(1) else: # Original file-based mode if len(sys.argv) < 3: print("Usage: python task_converter.py <input_markdown> <output_json>") print(" or: python task_converter.py --json-output <input_markdown>") sys.exit(1) input_file = sys.argv[1] output_file = sys.argv[2] success = convert_tasks(input_file, output_file) if success: print("\nJSON structure is compatible with Claude Code MCP format.") # Show example of how to use the output print("\nTo use this file with Claude Code MCP:") print("1. Configure your MCP server to use this JSON file") print("2. Start your MCP server with the command:") print(f" claude mcp add arangodb-validation -- node /path/to/server.js '{output_file}'") print("3. The tasks will be available to Claude through the MCP server") else: print("\nTask conversion failed.") sys.exit(1)