0xray 3.1.0 → 3.2.0

package/src/mcps/governance.server.ts

@@ -12,16 +12,15 @@
  * and the Dynamo Solar SSOT filter (required by default).
  */
 
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import {
   CallToolRequestSchema,
-  ListToolsRequestSchema,
   type CallToolResult,
 } from "@modelcontextprotocol/sdk/types.js";
+import { XrayKnowledgeSkillBase } from "./shared/knowledge-skill-base.js";
 import { mcpClientManager } from "./mcp-client.js";
 import { frameworkLogger } from "../core/framework-logger.js";
 import * as fs from "fs";
@@ -62,21 +61,104 @@ interface GovernReflectionArgs {
   context?: Record<string, unknown>;
 }
 
-class GovernanceServer {
-  private server: Server;
-
+class GovernanceServer extends XrayKnowledgeSkillBase {
   constructor() {
-    this.server = new Server(
+    super("governance", "3.1.0");
+    this.tools = [
       {
-        name: "governance", version: "1.22.67",
+        name: "govern_proposals",
+        description:
+          "Run one or more proposals through the full 0xRay governance system. " +
+          "Internal deliberation via 3 skill MCPs + required Dynamo Solar SSOT filter. " +
+          "Returns merged structured decisions. " +
+          "Supports regulatory compliance proposals: AML/KYC, PSD2, GDPR content moderation, " +
+          "and other compliance-related governance scenarios.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            proposals: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  id: { type: "string" },
+                  type: {
+                    type: "string",
+                    enum: ["fix", "refactor", "guard", "automate", "codify", "strategic", "compliance"],
+                  },
+                  title: { type: "string" },
+                  description: { type: "string" },
+                  evidence: { type: "array", items: { type: "string" } },
+                  source: { type: "string" },
+                  confidence: { type: "number" },
+                },
+                required: ["type", "title", "description"],
+              },
+              description: "List of proposals to govern",
+            },
+            context: {
+              type: "object",
+              description: "Optional context about the proposals (project, phase, etc.)",
+            },
+            options: {
+              type: "object",
+              properties: {
+                require_external: {
+                  type: "boolean",
+                  default: true,
+                  description: "Whether external Dynamo/Solar governance is required (default: true)",
+                },
+              },
+            },
+          },
+          required: ["proposals"],
+        },
       },
       {
-        capabilities: {
-          tools: {},
+        name: "govern_reflection",
+        description:
+          "Parse a reflection (or reflection file) and run its extracted proposals through the full governance system. " +
+          "This is the primary way to govern outcomes from reflection-based workflows.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            reflectionPath: {
+              type: "string",
+              description: "Path to a reflection .md file (alternative to reflectionContent)",
+            },
+            reflectionContent: {
+              type: "string",
+              description: "Raw reflection content (alternative to reflectionPath)",
+            },
+            context: { type: "object" },
+          },
+          required: [],
         },
-      }
-    );
-
+      },
+      {
+        name: "get_active_codex",
+        description:
+          "Get the currently active Codex (SSOT) — returns metadata about the loaded codex terms, " +
+          "including version, term count, source path, and governance status. " +
+          "Optionally include the full raw codex data with includeRaw=true.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            includeRaw: {
+              type: "boolean",
+              description: "Whether to include the full raw codex data in the response",
+              default: false,
+            },
+          },
+          required: [],
+        },
+      },
+    ];
+    this.handlers = {
+      "govern_proposals": async (args) => this.handleGovernProposals(this.validateGovernProposalsArgs(args)),
+      "govern_reflection": async (args) => this.handleGovernReflection(this.validateGovernReflectionArgs(args)),
+      "get_active_codex": async (args) => this.handleGetActiveCodex(args as { includeRaw?: boolean }),
+    };
     this.setupToolHandlers();
   }
 
@@ -113,101 +195,8 @@ class GovernanceServer {
     return value as GovernReflectionArgs;
   }
 
-  private setupToolHandlers() {
-    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-      return {
-        tools: [
-          {
-            name: "govern_proposals",
-            description:
-              "Run one or more proposals through the full 0xRay governance system. " +
-              "Internal deliberation via 3 skill MCPs + required Dynamo Solar SSOT filter. " +
-              "Returns merged structured decisions. " +
-              "Supports regulatory compliance proposals: AML/KYC, PSD2, GDPR content moderation, " +
-              "and other compliance-related governance scenarios.",
-            inputSchema: {
-              type: "object",
-              properties: {
-                proposals: {
-                  type: "array",
-                  items: {
-                    type: "object",
-                    properties: {
-                      id: { type: "string" },
-                      type: {
-                        type: "string",
-                        enum: ["fix", "refactor", "guard", "automate", "codify", "strategic", "compliance"],
-                      },
-                      title: { type: "string" },
-                      description: { type: "string" },
-                      evidence: { type: "array", items: { type: "string" } },
-                      source: { type: "string" },
-                      confidence: { type: "number" },
-                    },
-                    required: ["type", "title", "description"],
-                  },
-                  description: "List of proposals to govern",
-                },
-                context: {
-                  type: "object",
-                  description: "Optional context about the proposals (project, phase, etc.)",
-                },
-                options: {
-                  type: "object",
-                  properties: {
-                    require_external: {
-                      type: "boolean",
-                      default: true,
-                      description: "Whether external Dynamo/Solar governance is required (default: true)",
-                    },
-                  },
-                },
-              },
-              required: ["proposals"],
-            },
-          },
-          {
-            name: "govern_reflection",
-            description:
-              "Parse a reflection (or reflection file) and run its extracted proposals through the full governance system. " +
-              "This is the primary way to govern outcomes from reflection-based workflows.",
-            inputSchema: {
-              type: "object",
-              properties: {
-                reflectionPath: {
-                  type: "string",
-                  description: "Path to a reflection .md file (alternative to reflectionContent)",
-                },
-                reflectionContent: {
-                  type: "string",
-                  description: "Raw reflection content (alternative to reflectionPath)",
-                },
-                context: { type: "object" },
-              },
-              required: [],
-            },
-          },
-          {
-            name: "get_active_codex",
-            description:
-              "Get the currently active Codex (SSOT) — returns metadata about the loaded codex terms, " +
-              "including version, term count, source path, and governance status. " +
-              "Optionally include the full raw codex data with includeRaw=true.",
-            inputSchema: {
-              type: "object",
-              properties: {
-                includeRaw: {
-                  type: "boolean",
-                  description: "Whether to include the full raw codex data in the response",
-                  default: false,
-                },
-              },
-              required: [],
-            },
-          },
-        ],
-      };
-    });
+  protected setupToolHandlers(): void {
+    this.setupListToolsHandler();
 
     this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const { name, arguments: args } = request.params;
@@ -408,61 +397,7 @@ class GovernanceServer {
 
   async run(): Promise<void> {
     await this.initializeGovernance();
-
-    const transport = new StdioServerTransport();
-    await this.server.connect(transport);
-
-    let parentCheckTimer: ReturnType<typeof setTimeout> | null = null;
-
-    const cleanup = async (signal: string) => {
-      if (parentCheckTimer !== null) {
-        clearTimeout(parentCheckTimer);
-        parentCheckTimer = null;
-      }
-
-      const timeout = setTimeout(() => {
-        frameworkLogger.log("mcps/governance", "shutdown", "error", { message: "Graceful shutdown timeout, forcing exit..." });
-        process.exit(1);
-      }, 5000);
-
-      try {
-        if (this.server && typeof this.server.close === "function") {
-          await this.server.close();
-        }
-        clearTimeout(timeout);
-        process.exit(0);
-      } catch (error) {
-        clearTimeout(timeout);
-        frameworkLogger.log("mcps/governance", "shutdown", "error", { message: `Error during server shutdown: ${String(error)}` });
-        process.exit(1);
-      }
-    };
-
-    process.on("SIGINT", () => cleanup("SIGINT"));
-    process.on("SIGTERM", () => cleanup("SIGTERM"));
-    process.on("SIGHUP", () => cleanup("SIGHUP"));
-
-    const checkParent = () => {
-      try {
-        process.kill(process.ppid, 0);
-        parentCheckTimer = setTimeout(checkParent, 1000);
-      } catch (error) {
-        parentCheckTimer = null;
-        cleanup("parent-process-death");
-      }
-    };
-
-    parentCheckTimer = setTimeout(checkParent, 2000);
-
-    process.on("uncaughtException", (error) => {
-      frameworkLogger.log("mcps/governance", "uncaughtException", "error", { message: `Uncaught Exception: ${String(error)}` });
-      cleanup("uncaughtException");
-    });
-
-    process.on("unhandledRejection", (reason) => {
-      frameworkLogger.log("mcps/governance", "unhandledRejection", "error", { message: `Unhandled Rejection: ${String(reason)}` });
-      cleanup("unhandledRejection");
-    });
+    await super.run();
   }
 
   async connect(transport: Transport): Promise<void> {
@@ -475,7 +410,12 @@ class GovernanceServer {
   async runHttp(port: number = parseInt(process.env.MCP_PORT ?? "3100", 10)): Promise<void> {
     await this.initializeGovernance();
 
-    const app = createMcpExpressApp();
+    const mcpHost = process.env.MCP_HOST || "127.0.0.1";
+    const allowedHosts = process.env.MCP_ALLOWED_HOSTS?.split(",");
+    const app = createMcpExpressApp({
+      host: mcpHost,
+      ...(allowedHosts ? { allowedHosts } : {}),
+    });
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: () => randomUUID(),
     });
@@ -527,7 +467,7 @@ class GovernanceServer {
 }
 
 // Start the server if this file is run directly
-const entryPoint = path.resolve(process.argv[1] ?? "");
+const entryPoint = fs.realpathSync(process.argv[1] ?? "");
 if (entryPoint && fileURLToPath(import.meta.url) === entryPoint) {
   // If --port or MCP_PORT is set, use HTTP transport (for Grok CLI compatibility)
   const cliPort = process.argv.find((a) => a.startsWith("--port="))?.split("=")[1];

package/src/mcps/knowledge-skills/api-design.server.ts

@@ -5,12 +5,8 @@
  * GraphQL schema design, and API documentation standards
  */
 
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
+import { XrayKnowledgeSkillBase } from "../shared/knowledge-skill-base.js";
+import * as fs from "fs";
 import { frameworkLogger } from "../../core/framework-logger.js";
 import { createGracefulShutdown } from "../../utils/shutdown-handler.js";
 
@@ -25,74 +21,50 @@ interface ValidateApiDesignArgs {
   standards?: string[];
 }
 
-class XrayApiDesignServer {
-  private server: Server;
+class XrayApiDesignServer extends XrayKnowledgeSkillBase {
 
   constructor() {
-    this.server = new Server(
+    super("api-design", "3.1.0");
+
+    this.tools = [
       {
-        name: "api-design", version: "1.22.67",
+        name: "design-api-endpoints",
+        description:
+          "Design RESTful API endpoints with proper resource modeling",
+        inputSchema: {
+          type: "object",
+          properties: {
+            resource: { type: "string" },
+            operations: { type: "array", items: { type: "string" } },
+            relationships: { type: "array", items: { type: "string" } },
+          },
+          required: ["resource"],
+        },
       },
       {
-        capabilities: {
-          tools: {},
+        name: "validate-api-design",
+        description:
+          "Validate API design against RESTful principles and best practices",
+        inputSchema: {
+          type: "object",
+          properties: {
+            endpoints: { type: "array", items: { type: "string" } },
+            standards: { type: "array", items: { type: "string" } },
+          },
+          required: ["endpoints"],
         },
       },
-    );
+    ];
+
+    this.handlers = {
+      "design-api-endpoints": async (args) => this.designApiEndpoints(args as DesignApiEndpointsArgs),
+      "validate-api-design": async (args) => this.validateApiDesign(args as ValidateApiDesignArgs),
+    };
 
     this.setupToolHandlers();
     // Server initialization - removed unnecessary startup logging
   }
 
-  private setupToolHandlers() {
-    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-      return {
-        tools: [
-          {
-            name: "design-api-endpoints",
-            description:
-              "Design RESTful API endpoints with proper resource modeling",
-            inputSchema: {
-              type: "object",
-              properties: {
-                resource: { type: "string" },
-                operations: { type: "array", items: { type: "string" } },
-                relationships: { type: "array", items: { type: "string" } },
-              },
-              required: ["resource"],
-            },
-          },
-          {
-            name: "validate-api-design",
-            description:
-              "Validate API design against RESTful principles and best practices",
-            inputSchema: {
-              type: "object",
-              properties: {
-                endpoints: { type: "array", items: { type: "string" } },
-                standards: { type: "array", items: { type: "string" } },
-              },
-              required: ["endpoints"],
-            },
-          },
-        ],
-      };
-    });
-
-    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
-      const { name, arguments: args } = request.params;
-
-      switch (name) {
-        case "design-api-endpoints":
-          return await this.designApiEndpoints(args as unknown as DesignApiEndpointsArgs);
-        case "validate-api-design":
-          return await this.validateApiDesign(args as unknown as ValidateApiDesignArgs);
-        default:
-          throw new Error(`Unknown tool: ${name}`);
-      }
-    });
-  }
-
   private async designApiEndpoints(args: DesignApiEndpointsArgs) {
     const { resource, operations, relationships } = args;
 
@@ -140,19 +112,9 @@ class XrayApiDesignServer {
     };
   }
 
-  async run(): Promise<void> {
-    const transport = new StdioServerTransport();
-    await this.server.connect(transport);
-    
-    // Use centralized shutdown handler
-    createGracefulShutdown({
-      serverName: "api-design.server",
-      server: this.server,
-    });
-  }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (import.meta.url === `file://${fs.realpathSync(process.argv[1]!)}`) {
   const server = new XrayApiDesignServer();
   server.run().catch(() => {});
 }

package/src/mcps/knowledge-skills/architecture-patterns.server.ts

@@ -5,12 +5,7 @@
  * design pattern recommendations, and system architecture guidance
  */
 
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
+import { XrayKnowledgeSkillBase } from "../shared/knowledge-skill-base.js";
 import * as fs from "fs";
 import * as path from "path";
 import { frameworkLogger } from "../../core/framework-logger.js";
@@ -27,74 +22,50 @@ interface RecommendPatternsArgs {
   scale?: string;
 }
 
-class XrayArchitecturePatternsServer {
-  private server: Server;
+class XrayArchitecturePatternsServer extends XrayKnowledgeSkillBase {
 
   constructor() {
-    this.server = new Server(
+    super("architecture-patterns", "3.1.0");
+
+    this.tools = [
       {
-        name: "architecture-patterns", version: "1.22.67",
+        name: "analyze-architecture",
+        description:
+          "Analyze current system architecture and identify patterns",
+        inputSchema: {
+          type: "object",
+          properties: {
+            projectRoot: { type: "string" },
+            focusPatterns: { type: "array", items: { type: "string" } },
+          },
+          required: ["projectRoot"],
+        },
       },
       {
-        capabilities: {
-          tools: {},
+        name: "recommend-patterns",
+        description:
+          "Recommend architectural patterns for specific use cases",
+        inputSchema: {
+          type: "object",
+          properties: {
+            useCase: { type: "string" },
+            constraints: { type: "array", items: { type: "string" } },
+            scale: { type: "string", enum: ["small", "medium", "large"] },
+          },
+          required: ["useCase"],
         },
       },
-    );
+    ];
+
+    this.handlers = {
+      "analyze-architecture": async (args) => this.analyzeArchitecture(args as unknown as AnalyzeArchitectureArgs),
+      "recommend-patterns": async (args) => this.recommendPatterns(args as unknown as RecommendPatternsArgs),
+    };
 
     this.setupToolHandlers();
     // Server initialization - removed unnecessary startup logging
   }
 
-  private setupToolHandlers() {
-    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-      return {
-        tools: [
-          {
-            name: "analyze-architecture",
-            description:
-              "Analyze current system architecture and identify patterns",
-            inputSchema: {
-              type: "object",
-              properties: {
-                projectRoot: { type: "string" },
-                focusPatterns: { type: "array", items: { type: "string" } },
-              },
-              required: ["projectRoot"],
-            },
-          },
-          {
-            name: "recommend-patterns",
-            description:
-              "Recommend architectural patterns for specific use cases",
-            inputSchema: {
-              type: "object",
-              properties: {
-                useCase: { type: "string" },
-                constraints: { type: "array", items: { type: "string" } },
-                scale: { type: "string", enum: ["small", "medium", "large"] },
-              },
-              required: ["useCase"],
-            },
-          },
-        ],
-      };
-    });
-
-    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
-      const { name, arguments: args } = request.params;
-
-      switch (name) {
-        case "analyze-architecture":
-          return await this.analyzeArchitecture(args as unknown as AnalyzeArchitectureArgs);
-        case "recommend-patterns":
-          return await this.recommendPatterns(args as unknown as RecommendPatternsArgs);
-        default:
-          throw new Error(`Unknown tool: ${name}`);
-      }
-    });
-  }
-
   private async analyzeArchitecture(args: AnalyzeArchitectureArgs) {
     const { projectRoot, focusPatterns } = args;
 
@@ -132,19 +103,9 @@ class XrayArchitecturePatternsServer {
     };
   }
 
-  async run(): Promise<void> {
-    const transport = new StdioServerTransport();
-    await this.server.connect(transport);
-    
-    // Use centralized shutdown handler
-    createGracefulShutdown({
-      serverName: "architecture-patterns.server",
-      server: this.server,
-    });
-  }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (import.meta.url === `file://${fs.realpathSync(process.argv[1]!)}`) {
   const server = new XrayArchitecturePatternsServer();
   server.run().catch(() => {});
 }