MCP WordPress Server

# API Reference Complete technical reference for the MCP WordPress Server API, tools, and interfaces. ## 🔧 Core API Classes ### WordPressClient Primary interface for WordPress REST API communication. ```typescript class WordPressClient { constructor(config: ClientConfig); // Core managers auth: AuthenticationManager; request: RequestManager; cache: CacheManager; // Content APIs posts: PostsAPI; pages: PagesAPI; media: MediaAPI; users: UsersAPI; comments: CommentsAPI; taxonomies: TaxonomiesAPI; // Site management settings: SettingsAPI; plugins: PluginsAPI; themes: ThemesAPI; } ``` **Configuration Interface**: ```typescript interface ClientConfig { siteUrl: string; username: string; password?: string; appPassword?: string; authMethod?: "app-password" | "jwt" | "basic" | "api-key"; timeout?: number; retryAttempts?: number; cacheEnabled?: boolean; debug?: boolean; } ``` ### AuthenticationManager Handles multiple WordPress authentication methods. ```typescript class AuthenticationManager { // Authentication methods async authenticateWithAppPassword(username: string, password: string): Promise<AuthResult>; async authenticateWithJWT(username: string, password: string): Promise<AuthResult>; async authenticateWithBasic(username: string, password: string): Promise<AuthResult>; async authenticateWithApiKey(apiKey: string): Promise<AuthResult>; // Token management async refreshToken(): Promise<string>; async validateToken(token: string): Promise<boolean>; async revokeToken(token: string): Promise<void>; // Headers getAuthHeaders(): Record<string, string>; isAuthenticated(): boolean; } ``` ### RequestManager HTTP request handling with retry logic and rate limiting. ```typescript class RequestManager { // HTTP methods async get<T>(endpoint: string, params?: QueryParams): Promise<T>; async post<T>(endpoint: string, data?: any): Promise<T>; async put<T>(endpoint: string, data?: any): Promise<T>; async patch<T>(endpoint: string, data?: any): Promise<T>; async delete<T>(endpoint: string): Promise<T>; // Batch operations async batchRequest<T>(requests: BatchRequest[]): Promise<T[]>; // File uploads async uploadFile(file: File, options?: UploadOptions): Promise<MediaItem>; // Rate limiting async waitForRateLimit(): Promise<void>; getRateLimitStatus(): RateLimitStatus; } ``` ## 📝 MCP Tools API ### Tool Categories #### Posts Tools (PostTools) ```typescript class PostTools { // Content management async createPost(params: CreatePostParams): Promise<PostResult>; async updatePost(params: UpdatePostParams): Promise<PostResult>; async deletePost(params: DeletePostParams): Promise<DeleteResult>; async getPost(params: GetPostParams): Promise<PostResult>; async listPosts(params: ListPostsParams): Promise<PostListResult>; async getPostRevisions(params: GetPostRevisionsParams): Promise<PostRevisionsResult>; } ``` **Parameter Interfaces**: ```typescript interface CreatePostParams { title: string; content?: string; excerpt?: string; status?: "draft" | "publish" | "private" | "pending"; author?: number; categories?: number[]; tags?: number[]; featured_media?: number; meta?: Record<string, any>; site?: string; // Multi-site support } interface PostResult { id: number; title: string; content: string; excerpt: string; status: string; author: number; date: string; modified: string; link: string; slug: string; categories: number[]; tags: number[]; featured_media: number; meta: Record<string, any>; } ``` #### Pages Tools (PageTools) ```typescript class PageTools { async createPage(params: CreatePageParams): Promise<PageResult>; async updatePage(params: UpdatePageParams): Promise<PageResult>; async deletePage(params: DeletePageParams): Promise<DeleteResult>; async getPage(params: GetPageParams): Promise<PageResult>; async listPages(params: ListPagesParams): Promise<PageListResult>; async getPageRevisions(params: GetPageRevisionsParams): Promise<PageRevisionsResult>; } ``` #### Media Tools (MediaTools) ```typescript class MediaTools { async uploadMedia(params: UploadMediaParams): Promise<MediaResult>; async updateMedia(params: UpdateMediaParams): Promise<MediaResult>; async deleteMedia(params: DeleteMediaParams): Promise<DeleteResult>; async getMedia(params: GetMediaParams): Promise<MediaResult>; async listMedia(params: ListMediaParams): Promise<MediaListResult>; } ``` **Upload Parameters**: ```typescript interface UploadMediaParams { file: string | Buffer; // File path or buffer filename?: string; title?: string; alt_text?: string; caption?: string; description?: string; post?: number; // Attach to specific post site?: string; } ``` #### Users Tools (UserTools) ```typescript class UserTools { async createUser(params: CreateUserParams): Promise<UserResult>; async updateUser(params: UpdateUserParams): Promise<UserResult>; async deleteUser(params: DeleteUserParams): Promise<DeleteResult>; async getUser(params: GetUserParams): Promise<UserResult>; async listUsers(params: ListUsersParams): Promise<UserListResult>; async getCurrentUser(params: GetCurrentUserParams): Promise<UserResult>; } ``` #### Comments Tools (CommentTools) ```typescript class CommentTools { async createComment(params: CreateCommentParams): Promise<CommentResult>; async updateComment(params: UpdateCommentParams): Promise<CommentResult>; async deleteComment(params: DeleteCommentParams): Promise<DeleteResult>; async getComment(params: GetCommentParams): Promise<CommentResult>; async listComments(params: ListCommentsParams): Promise<CommentListResult>; async moderateComment(params: ModerateCommentParams): Promise<CommentResult>; async bulkModerateComments(params: BulkModerateCommentsParams): Promise<BulkResult>; } ``` #### Taxonomies Tools (TaxonomyTools) ```typescript class TaxonomyTools { // Categories async createCategory(params: CreateCategoryParams): Promise<CategoryResult>; async updateCategory(params: UpdateCategoryParams): Promise<CategoryResult>; async deleteCategory(params: DeleteCategoryParams): Promise<DeleteResult>; async getCategory(params: GetCategoryParams): Promise<CategoryResult>; async listCategories(params: ListCategoriesParams): Promise<CategoryListResult>; // Tags async createTag(params: CreateTagParams): Promise<TagResult>; async updateTag(params: UpdateTagParams): Promise<TagResult>; async deleteTag(params: DeleteTagParams): Promise<DeleteResult>; async getTag(params: GetTagParams): Promise<TagResult>; async listTags(params: ListTagsParams): Promise<TagListResult>; } ``` #### Site Tools (SiteTools) ```typescript class SiteTools { async getSiteInfo(params: GetSiteInfoParams): Promise<SiteInfoResult>; async updateSiteSettings(params: UpdateSiteSettingsParams): Promise<SiteSettingsResult>; async getSiteStats(params: GetSiteStatsParams): Promise<SiteStatsResult>; async getPlugins(params: GetPluginsParams): Promise<PluginsResult>; async getThemes(params: GetThemesParams): Promise<ThemesResult>; async searchContent(params: SearchContentParams): Promise<SearchResult>; } ``` #### Authentication Tools (AuthTools) ```typescript class AuthTools { async testAuth(params: TestAuthParams): Promise<AuthTestResult>; async refreshToken(params: RefreshTokenParams): Promise<TokenResult>; async validatePermissions(params: ValidatePermissionsParams): Promise<PermissionsResult>; } ``` #### Cache Tools (CacheTools) ```typescript class CacheTools { async getCacheStats(params: GetCacheStatsParams): Promise<CacheStatsResult>; async clearCache(params: ClearCacheParams): Promise<ClearCacheResult>; async warmCache(params: WarmCacheParams): Promise<WarmCacheResult>; async setCacheConfig(params: SetCacheConfigParams): Promise<CacheConfigResult>; } ``` #### Performance Tools (PerformanceTools) ```typescript class PerformanceTools { async getPerformanceMetrics(params: GetPerformanceMetricsParams): Promise<PerformanceMetricsResult>; async runPerformanceTest(params: RunPerformanceTestParams): Promise<PerformanceTestResult>; async getSystemHealth(params: GetSystemHealthParams): Promise<SystemHealthResult>; async benchmarkOperations(params: BenchmarkOperationsParams): Promise<BenchmarkResult>; async getOptimizationSuggestions(params: GetOptimizationSuggestionsParams): Promise<OptimizationResult>; async monitorRealTimeMetrics(params: MonitorRealTimeMetricsParams): Promise<RealTimeMetricsResult>; } ``` ## 🔒 Security API ### Input Validation All tools use Zod schemas for parameter validation: ```typescript const createPostSchema = z.object({ title: z.string().min(1).max(200), content: z.string().optional(), status: z.enum(["draft", "publish", "private", "pending"]).optional(), author: z.number().positive().optional(), categories: z.array(z.number().positive()).optional(), tags: z.array(z.number().positive()).optional(), site: z.string().optional(), }); ``` ### Error Handling ```typescript interface APIError { code: string; message: string; details?: any; statusCode?: number; } class WordPressAPIError extends Error { constructor( public code: string, message: string, public statusCode?: number, public details?: any, ) { super(message); this.name = "WordPressAPIError"; } } ``` ### Rate Limiting ```typescript interface RateLimitStatus { limit: number; remaining: number; reset: Date; retryAfter?: number; } class RateLimitManager { async checkRateLimit(endpoint: string): Promise<RateLimitStatus>; async waitForRateLimit(endpoint: string): Promise<void>; isRateLimited(endpoint: string): boolean; } ``` ## 📊 Performance API ### Metrics Collection ```typescript interface PerformanceMetric { timestamp: Date; operation: string; duration: number; endpoint: string; success: boolean; cacheHit?: boolean; error?: string; } class MetricsCollector { collect(metric: PerformanceMetric): void; getMetrics(filter?: MetricFilter): PerformanceMetric[]; getAggregatedMetrics(period: TimePeriod): AggregatedMetrics; } ``` ### Cache Management ```typescript interface CacheEntry<T> { key: string; value: T; timestamp: Date; ttl: number; size: number; } class CacheManager { async get<T>(key: string): Promise<T | null>; async set<T>(key: string, value: T, ttl?: number): Promise<void>; async del(key: string): Promise<void>; async clear(pattern?: string): Promise<void>; // Cache statistics getStats(): CacheStats; getSize(): number; getHitRate(): number; } ``` ## 🛠️ Configuration API ### Multi-Site Configuration ```typescript interface MultiSiteConfig { sites: SiteConfig[]; } interface SiteConfig { id: string; name: string; config: { WORDPRESS_SITE_URL: string; WORDPRESS_USERNAME: string; WORDPRESS_APP_PASSWORD: string; WORDPRESS_AUTH_METHOD?: AuthMethod; }; } ``` ### Environment Configuration ```typescript interface EnvironmentConfig { WORDPRESS_SITE_URL: string; WORDPRESS_USERNAME: string; WORDPRESS_APP_PASSWORD?: string; WORDPRESS_AUTH_METHOD?: AuthMethod; DEBUG?: boolean; CACHE_ENABLED?: boolean; CACHE_TTL?: number; REQUEST_TIMEOUT?: number; RETRY_ATTEMPTS?: number; } ``` ## 🧪 Testing API ### Test Utilities ```typescript class TestUtils { static createMockClient(config?: Partial<ClientConfig>): WordPressClient; static createMockPost(overrides?: Partial<Post>): Post; static createMockUser(overrides?: Partial<User>): User; static generateTestData<T>(schema: ZodSchema<T>): T; } ``` ### Test Fixtures ```typescript interface TestFixtures { posts: Post[]; users: User[]; comments: Comment[]; categories: Category[]; tags: Tag[]; media: MediaItem[]; } class FixtureManager { static loadFixtures(): TestFixtures; static createTestSite(): Promise<TestSite>; static cleanupTestSite(site: TestSite): Promise<void>; } ``` ## 📚 Type Definitions ### WordPress Types ```typescript interface Post { id: number; title: string; content: string; excerpt: string; status: PostStatus; author: number; date: string; modified: string; link: string; slug: string; categories: number[]; tags: number[]; featured_media: number; meta: Record<string, any>; } interface User { id: number; username: string; email: string; first_name: string; last_name: string; nickname: string; description: string; link: string; avatar_urls: Record<string, string>; roles: string[]; capabilities: Record<string, boolean>; meta: Record<string, any>; } interface Comment { id: number; post: number; parent: number; author: number; author_name: string; author_email: string; author_url: string; content: string; date: string; status: CommentStatus; meta: Record<string, any>; } ``` ### MCP Types ```typescript interface MCPTool { name: string; description: string; inputSchema: JSONSchema; handler: ToolHandler; } interface ToolHandler { (params: any): Promise<ToolResult>; } interface ToolResult { success: boolean; data?: any; error?: string; metadata?: Record<string, any>; } ``` ## 🔍 Debugging API ### Debug Utilities ```typescript class DebugLogger { static log(level: LogLevel, message: string, context?: any): void; static error(error: Error, context?: any): void; static performance(operation: string, duration: number): void; static http(method: string, url: string, status: number, duration: number): void; } ``` ### Health Check API ```typescript interface HealthCheck { status: "healthy" | "degraded" | "unhealthy"; checks: { database: HealthStatus; cache: HealthStatus; authentication: HealthStatus; performance: HealthStatus; }; timestamp: Date; } class HealthChecker { async checkHealth(): Promise<HealthCheck>; async checkDatabase(): Promise<HealthStatus>; async checkCache(): Promise<HealthStatus>; async checkAuthentication(): Promise<HealthStatus>; } ``` ## 📖 Usage Examples ### Basic Client Usage ```typescript import { WordPressClient } from "mcp-wordpress"; const client = new WordPressClient({ siteUrl: "https://your-site.com", username: "admin", appPassword: "xxxx xxxx xxxx xxxx xxxx xxxx", authMethod: "app-password", }); // Create a post const post = await client.posts.create({ title: "My New Post", content: "This is the post content", status: "publish", }); ``` ### Multi-Site Usage ```typescript import { MCPWordPressServer } from "mcp-wordpress"; const server = new MCPWordPressServer({ sites: [ { id: "site1", name: "Main Site", config: { WORDPRESS_SITE_URL: "https://site1.com", WORDPRESS_USERNAME: "admin", WORDPRESS_APP_PASSWORD: "password1", }, }, { id: "site2", name: "Blog Site", config: { WORDPRESS_SITE_URL: "https://site2.com", WORDPRESS_USERNAME: "editor", WORDPRESS_APP_PASSWORD: "password2", }, }, ], }); ``` ## 📚 Further Reading - **[Architecture Guide](ARCHITECTURE.md)** - System design and patterns - **[Testing Guide](TESTING.md)** - Test suite and best practices - **[Security Guidelines](SECURITY_DEVELOPMENT.md)** - Security best practices - **[Performance Guide](PERFORMANCE_DEVELOPMENT.md)** - Performance optimization --- **Need more details?** This API reference covers the complete technical interface. For implementation examples, see the source code in `src/` directory.