WP Navigator MCP

# Source Directory Context ## Module Responsibilities ### Entry Points - `index.ts` - MCP server setup, request routing via tool registry - `setup.ts` - Interactive setup wizard (if present) ### Core Infrastructure - `config.ts` - Config loading from JSON file or env vars; exports `WPConfig` type - `http.ts` - `makeWpRequest()` factory; handles auth, retry, TLS enforcement, error formatting - `logger.ts` - Logging utilities for debug/info/error - `validation.ts` - Input validation for tool arguments - `output.ts` - Response formatting, text clamping ### Safety Layer - `safety.ts` - Plan/Diff/Apply workflow for safe content changes - `startup-validator.ts` - Pre-flight checks (connectivity, auth, plugin presence) ### Tool System - `tools.ts` - Legacy 48-tool definitions (being migrated to registry) - `tool-registry/` - New registry pattern: - `registry.ts` - Central `ToolRegistry` class, singleton `toolRegistry` - `types.ts` - `RegisteredTool`, `ToolCategory`, `ToolExecutionContext` - `utils.ts` - Shared validation: `validateRequired()`, `validatePagination()`, etc. ### Tool Implementations - `tools/core/` - introspect, help - `tools/content/` - posts, pages, media, comments - `tools/taxonomy/` - categories, tags - `tools/users/` - user CRUD - `tools/plugins/` - plugin CRUD - `tools/themes/` - theme CRUD - `tools/gutenberg/` - block editor operations - `tools/testing/` - test utilities ## Key Patterns ### Adding a Tool ```typescript import { toolRegistry, ToolCategory } from '../tool-registry/index.js'; import { validateRequired, validateId } from '../tool-registry/utils.js'; toolRegistry.register({ definition: { name: 'wpnav_my_tool', description: 'Tool description for AI agents', inputSchema: { type: 'object', properties: {...}, required: [...] }, }, handler: async (args, context) => { validateRequired(args, ['id']); const response = await context.wpRequest('/wp-json/wp/v2/posts/' + args.id); return { content: [{ type: 'text', text: JSON.stringify(response, null, 2) }] }; }, category: ToolCategory.CONTENT, }); ``` ### Error Handling - Let errors bubble up; registry wraps them - Use descriptive messages for AI agent debugging - `http.ts` provides enhanced error formatting with remediation steps ### Response Format Always return MCP-compliant: ```typescript return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], }; ``` ## Testing - Unit tests: `*.test.ts` alongside source - Integration tests: `tests/` directory - Run: `npm test` or `npm run test:watch`