mcp-wordpress 1.3.0 → 1.4.0

package/docs/developer/API_REFERENCE.md

@@ -0,0 +1,628 @@
+# 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.