mcp-wordpress 1.1.2

package/src/types/index.ts

@@ -0,0 +1,207 @@
+/**
+ * Type Exports
+ * 
+ * Central export point for all TypeScript types
+ */
+
+// WordPress API Types
+export * from './wordpress.js';
+
+// MCP Types
+export * from './mcp.js';
+
+// Client Types
+export * from './client.js';
+
+// Common Utility Types
+export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+export type RequiredKeys<T, K extends keyof T> = T & Required<Pick<T, K>>;
+export type Nullable<T> = T | null;
+export type AsyncResult<T> = Promise<T>;
+
+// Generic ID type
+export type ID = number | string;
+
+// Generic Error Response
+export interface ErrorResponse {
+  error: true;
+  message: string;
+  code?: string;
+  details?: Record<string, any>;
+}
+
+// Generic Success Response
+export interface SuccessResponse<T = any> {
+  success: true;
+  data: T;
+  message?: string;
+}
+
+// Combined Response Type
+export type APIResult<T> = SuccessResponse<T> | ErrorResponse;
+
+// Pagination Metadata
+export interface PaginationMeta {
+  page: number;
+  per_page: number;
+  total: number;
+  total_pages: number;
+  has_next: boolean;
+  has_previous: boolean;
+}
+
+// Paginated Response
+export interface PaginatedResponse<T> {
+  data: T[];
+  meta: PaginationMeta;
+  links?: {
+    first?: string;
+    last?: string;
+    next?: string;
+    previous?: string;
+  };
+}
+
+// Configuration Types
+export interface DatabaseConfig {
+  host: string;
+  port: number;
+  name: string;
+  user: string;
+  password: string;
+  charset?: string;
+  collate?: string;
+}
+
+export interface LoggingConfig {
+  level: 'debug' | 'info' | 'warn' | 'error';
+  file?: string;
+  console?: boolean;
+  format?: 'json' | 'text';
+}
+
+export interface ServerConfig {
+  host: string;
+  port: number;
+  env: 'development' | 'production' | 'test';
+  debug: boolean;
+  logging: LoggingConfig;
+}
+
+// Environment Variables Type
+export interface Environment {
+  WORDPRESS_SITE_URL: string;
+  WORDPRESS_USERNAME: string;
+  WORDPRESS_APP_PASSWORD?: string;
+  WORDPRESS_PASSWORD?: string;
+  WORDPRESS_AUTH_METHOD: string;
+  WORDPRESS_JWT_SECRET?: string;
+  WORDPRESS_API_KEY?: string;
+  DEBUG?: string;
+  NODE_ENV?: string;
+  LOG_LEVEL?: string;
+}
+
+// Validation Schema Types
+export interface ValidationRule {
+  type: 'required' | 'string' | 'number' | 'boolean' | 'email' | 'url' | 'enum' | 'array' | 'object';
+  message?: string;
+  min?: number;
+  max?: number;
+  pattern?: RegExp;
+  enum_values?: any[];
+  custom?: (value: any) => boolean | string;
+}
+
+export interface ValidationSchema {
+  [field: string]: ValidationRule | ValidationRule[];
+}
+
+// Cache Types
+export interface CacheEntry<T> {
+  value: T;
+  expiry: number;
+  created: number;
+}
+
+export interface CacheOptions {
+  ttl?: number; // time to live in milliseconds
+  maxSize?: number;
+  strategy?: 'lru' | 'fifo' | 'ttl';
+}
+
+// Event Types
+export interface EventData {
+  type: string;
+  timestamp: number;
+  data?: Record<string, any>;
+}
+
+export type EventHandler<T = EventData> = (event: T) => void | Promise<void>;
+
+// Performance Metrics
+export interface PerformanceMetric {
+  name: string;
+  duration: number;
+  timestamp: number;
+  metadata?: Record<string, any>;
+}
+
+// Health Check Types
+export interface HealthStatus {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  timestamp: number;
+  checks: Record<string, {
+    status: 'pass' | 'fail' | 'warn';
+    message?: string;
+    duration?: number;
+  }>;
+  uptime: number;
+  version: string;
+}
+
+// Debugging Types
+export interface DebugInfo {
+  timestamp: number;
+  level: 'debug' | 'info' | 'warn' | 'error';
+  message: string;
+  context?: Record<string, any>;
+  stack?: string;
+}
+
+// Type Utilities
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+export type DeepRequired<T> = {
+  [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P];
+};
+
+export type KeysOfType<T, U> = {
+  [K in keyof T]: T[K] extends U ? K : never;
+}[keyof T];
+
+export type Awaited<T> = T extends Promise<infer U> ? U : T;
+
+// Brand types for better type safety
+export type Brand<T, B> = T & { __brand: B };
+
+export type WordPressID = Brand<number, 'WordPressID'>;
+export type UserID = Brand<number, 'UserID'>;
+export type PostID = Brand<number, 'PostID'>;
+export type MediaID = Brand<number, 'MediaID'>;
+export type CommentID = Brand<number, 'CommentID'>;
+export type CategoryID = Brand<number, 'CategoryID'>;
+export type TagID = Brand<number, 'TagID'>;
+
+// Function Types
+export type AsyncFunction<TArgs extends any[] = any[], TReturn = any> = (...args: TArgs) => Promise<TReturn>;
+export type SyncFunction<TArgs extends any[] = any[], TReturn = any> = (...args: TArgs) => TReturn;
+export type AnyFunction<TArgs extends any[] = any[], TReturn = any> = SyncFunction<TArgs, TReturn> | AsyncFunction<TArgs, TReturn>;
+
+// Conditional Types
+export type If<C extends boolean, T, F> = C extends true ? T : F;
+export type IsEqual<T, U> = T extends U ? (U extends T ? true : false) : false;
+export type IsArray<T> = T extends any[] ? true : false;
+export type IsObject<T> = T extends object ? (T extends any[] ? false : true) : false;

package/src/types/mcp.ts

@@ -0,0 +1,247 @@
+/**
+ * Model Context Protocol (MCP) Types
+ * 
+ * TypeScript definitions for MCP tools, requests, and responses
+ */
+
+import type { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+// MCP Tool Schema Types
+export interface MCPToolSchema {
+  type: 'object';
+  properties: Record<string, JSONSchemaProperty>;
+  required?: string[];
+  additionalProperties?: boolean;
+}
+
+export interface JSONSchemaProperty {
+  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  description?: string;
+  enum?: (string | number)[];
+  items?: JSONSchemaProperty;
+  properties?: Record<string, JSONSchemaProperty>;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+  default?: any;
+}
+
+// MCP Tool Definition
+export interface MCPTool {
+  name: string;
+  description: string;
+  inputSchema: MCPToolSchema;
+}
+
+// MCP Content Types
+export interface MCPTextContent {
+  type: 'text';
+  text: string;
+}
+
+export interface MCPImageContent {
+  type: 'image';
+  data: string;
+  mimeType: string;
+}
+
+export interface MCPResourceContent {
+  type: 'resource';
+  resource: {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+  };
+}
+
+export type MCPContent = MCPTextContent | MCPImageContent | MCPResourceContent;
+
+// MCP Response Types
+export interface MCPToolResponse {
+  content: MCPContent[];
+  isError?: boolean;
+}
+
+export interface MCPSuccessResponse extends MCPToolResponse {
+  isError?: false;
+}
+
+export interface MCPErrorResponse extends MCPToolResponse {
+  isError: true;
+}
+
+// MCP Tool Handler Type
+export type MCPToolHandler<TArgs = any, TResponse = MCPToolResponse> = (
+  args: TArgs
+) => Promise<TResponse>;
+
+// Generic MCP Tool Handler with Client
+export type MCPToolHandlerWithClient<TClient, TArgs = any, TResponse = MCPToolResponse> = (
+  client: TClient,
+  args: TArgs
+) => Promise<TResponse>;
+
+// MCP Request Types (based on SDK)
+export type MCPListToolsRequest = typeof ListToolsRequestSchema;
+export type MCPCallToolRequest = typeof CallToolRequestSchema;
+
+// Tool Categories for Organization
+export type MCPToolCategory = 
+  | 'authentication'
+  | 'posts'
+  | 'pages'
+  | 'media'
+  | 'users'
+  | 'comments'
+  | 'taxonomies'
+  | 'site';
+
+// Enhanced Tool Definition with Category
+export interface CategorizedMCPTool extends MCPTool {
+  category: MCPToolCategory;
+}
+
+// Tool Registry Type
+export type MCPToolRegistry = Record<string, CategorizedMCPTool>;
+
+// Handler Registry Type
+export type MCPHandlerRegistry<TClient> = Record<string, MCPToolHandlerWithClient<TClient>>;
+
+// Tool Validation Result
+export interface ToolValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+// Common Response Helpers
+export type CreateSuccessResponse = (text: string, additionalContent?: MCPContent[]) => MCPSuccessResponse;
+export type CreateErrorResponse = (error: string | Error, additionalContent?: MCPContent[]) => MCPErrorResponse;
+
+// Authentication Response Types
+export interface AuthenticationResult {
+  success: boolean;
+  method: string;
+  message: string;
+  details?: Record<string, any>;
+}
+
+// Tool Execution Context
+export interface MCPToolContext {
+  toolName: string;
+  category: MCPToolCategory;
+  startTime: number;
+  userId?: string;
+  sessionId?: string;
+}
+
+// Tool Metrics
+export interface MCPToolMetrics {
+  executionTime: number;
+  success: boolean;
+  errorType?: string;
+  inputSize?: number;
+  outputSize?: number;
+}
+
+// Enhanced Error Types
+export interface MCPToolError extends Error {
+  toolName: string;
+  category: MCPToolCategory;
+  code?: string;
+  statusCode?: number;
+  details?: Record<string, any>;
+}
+
+// Tool Configuration
+export interface MCPToolConfig {
+  timeout?: number;
+  retries?: number;
+  rateLimit?: {
+    requests: number;
+    window: number; // in milliseconds
+  };
+  validation?: {
+    strict: boolean;
+    allowAdditionalProperties: boolean;
+  };
+}
+
+// Server Configuration
+export interface MCPServerConfig {
+  name: string;
+  version: string;
+  tools: MCPToolRegistry;
+  handlers: MCPHandlerRegistry<any>;
+  middleware?: MCPMiddleware[];
+  config?: MCPToolConfig;
+}
+
+// Middleware Type
+export type MCPMiddleware<TClient = any> = (
+  context: MCPToolContext,
+  next: () => Promise<MCPToolResponse>
+) => Promise<MCPToolResponse>;
+
+// Tool Execution Pipeline
+export interface MCPExecutionPipeline<TClient> {
+  validate: (toolName: string, args: any) => Promise<ToolValidationResult>;
+  authenticate: (client: TClient) => Promise<boolean>;
+  execute: (toolName: string, client: TClient, args: any) => Promise<MCPToolResponse>;
+  postProcess: (response: MCPToolResponse, context: MCPToolContext) => Promise<MCPToolResponse>;
+}
+
+// Tool Documentation
+export interface MCPToolDocumentation {
+  name: string;
+  category: MCPToolCategory;
+  description: string;
+  usage: string;
+  examples: Array<{
+    title: string;
+    description: string;
+    input: Record<string, any>;
+    output: string;
+  }>;
+  parameters: Array<{
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+    example?: any;
+  }>;
+  errors: Array<{
+    code: string;
+    description: string;
+    resolution: string;
+  }>;
+}
+
+// Batch Operation Types
+export interface MCPBatchRequest {
+  operations: Array<{
+    toolName: string;
+    args: Record<string, any>;
+    id?: string;
+  }>;
+  parallel?: boolean;
+  stopOnError?: boolean;
+}
+
+export interface MCPBatchResponse {
+  results: Array<{
+    id?: string;
+    success: boolean;
+    response?: MCPToolResponse;
+    error?: MCPToolError;
+  }>;
+  summary: {
+    total: number;
+    successful: number;
+    failed: number;
+    executionTime: number;
+  };
+}