offrouter-mcp 0.0.0

package/src/tools/cancel.ts

@@ -0,0 +1,73 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { OffRouterMcpContext } from "../server.js";
+
+const inputSchema = {
+  taskId: z.string().min(1),
+};
+
+const outputSchema = {
+  cancelled: z.boolean(),
+  task: z.record(z.unknown()).optional(),
+  error: z
+    .object({
+      code: z.string(),
+      message: z.string(),
+    })
+    .optional(),
+};
+
+/**
+ * Cancel a same-process background delegation task started by this MCP server.
+ */
+export function registerCancelTool(
+  server: McpServer,
+  context: OffRouterMcpContext,
+): void {
+  server.registerTool(
+    "offrouter_cancel",
+    {
+      title: "OffRouter cancel",
+      description:
+        "Cancel an active background delegation task that lives in this MCP server process only.",
+      inputSchema,
+      outputSchema,
+    },
+    async (args) => {
+      const task = await context.runtime.cancel(args.taskId);
+      if (!task) {
+        const structuredContent = {
+          cancelled: false,
+          task: undefined,
+          error: {
+            code: "unknown_task",
+            message: `No active task found for ${args.taskId}.`,
+          },
+        };
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(structuredContent, null, 2),
+            },
+          ],
+          structuredContent,
+        };
+      }
+
+      const structuredContent = {
+        cancelled: task.status === "cancelled",
+        task,
+      };
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(structuredContent, null, 2),
+          },
+        ],
+        structuredContent,
+      };
+    },
+  );
+}

package/src/tools/delegate.ts

@@ -0,0 +1,225 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  DelegationPolicyError,
+  RouteRequestSchema,
+  type DelegationMode,
+  type DelegationEvent,
+  type DelegationOutput,
+  type DelegationRequest,
+} from "offrouter-core";
+import { z } from "zod";
+import { newTaskId, type OffRouterMcpContext } from "../server.js";
+
+const ModeSchema = z.enum(["oneshot", "stream", "background"]);
+const OutputSchema = z.enum(["text", "json", "patch"]);
+
+const inputSchema = {
+  prompt: z.string().min(1),
+  route: RouteRequestSchema,
+  mode: ModeSchema.default("oneshot"),
+  output: OutputSchema.default("text"),
+  taskId: z.string().min(1).optional(),
+  model: z.string().min(1).optional(),
+  providerId: z.string().min(1).optional(),
+  maxOutputTokens: z.number().int().positive().optional(),
+  temperature: z.number().optional(),
+};
+
+const outputSchema = {
+  result: z.record(z.unknown()).optional(),
+  decision: z.record(z.unknown()).optional(),
+  task: z.record(z.unknown()).optional(),
+};
+
+function toDelegationRequest(args: {
+  prompt: string;
+  route: DelegationRequest["route"];
+  mode: DelegationMode;
+  output: DelegationOutput;
+  taskId?: string;
+  model?: string;
+  providerId?: string;
+  maxOutputTokens?: number;
+  temperature?: number;
+}): DelegationRequest {
+  return {
+    taskId: args.taskId ?? newTaskId(),
+    mode: args.mode,
+    output: args.output,
+    prompt: args.prompt,
+    route: args.route,
+    model: args.model,
+    providerId: args.providerId,
+    maxOutputTokens: args.maxOutputTokens,
+    temperature: args.temperature,
+  };
+}
+
+export function registerDelegateTool(
+  server: McpServer,
+  context: OffRouterMcpContext,
+): void {
+  server.registerTool(
+    "offrouter_delegate",
+    {
+      title: "OffRouter delegate",
+      description:
+        "Route then invoke an allowed provider. Full prompt is only sent after policy allows. Background tasks run only in this MCP process.",
+      inputSchema,
+      outputSchema,
+    },
+    async (args) => {
+      const mode = (args.mode ?? "oneshot") as DelegationMode;
+      const output = (args.output ?? "text") as DelegationOutput;
+      const request = toDelegationRequest({
+        prompt: args.prompt,
+        route: args.route,
+        mode,
+        output,
+        taskId: args.taskId,
+        model: args.model,
+        providerId: args.providerId,
+        maxOutputTokens: args.maxOutputTokens,
+        temperature: args.temperature,
+      });
+
+      if (mode === "background") {
+        try {
+          const task = await context.runtime.startBackground(request);
+          const structuredContent = { task };
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify(structuredContent, null, 2),
+              },
+            ],
+            structuredContent,
+          };
+        } catch (err) {
+          if (err instanceof DelegationPolicyError) {
+            const structuredContent = {
+              task: {
+                taskId: request.taskId,
+                status: "failed",
+              },
+              decision: err.decision,
+              result: {
+                status: "failed",
+                error: err.message,
+              },
+            };
+            return {
+              content: [
+                {
+                  type: "text" as const,
+                  text: JSON.stringify(structuredContent, null, 2),
+                },
+              ],
+              structuredContent,
+            };
+          }
+          throw err;
+        }
+      }
+
+      if (mode === "stream") {
+        try {
+          const events: DelegationEvent[] = [];
+          for await (const event of context.runtime.stream(request)) {
+            events.push(event);
+          }
+          const task = context.runtime.getTask(request.taskId);
+          const structuredContent = {
+            result: {
+              status: task?.status ?? "failed",
+              text: task?.text,
+              error: task?.error,
+              taskId: request.taskId,
+              events,
+            },
+            decision: task?.decision,
+          };
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify(structuredContent, null, 2),
+              },
+            ],
+            structuredContent,
+          };
+        } catch (err) {
+          if (err instanceof DelegationPolicyError) {
+            const structuredContent = {
+              result: {
+                status: "failed",
+                error: err.message,
+                taskId: request.taskId,
+                events: context.runtime.getTask(request.taskId)?.events ?? [],
+              },
+              decision: err.decision,
+            };
+            return {
+              content: [
+                {
+                  type: "text" as const,
+                  text: JSON.stringify(structuredContent, null, 2),
+                },
+              ],
+              structuredContent,
+            };
+          }
+          throw err;
+        }
+      }
+
+      // oneshot
+      try {
+        const result = await context.runtime.delegate({
+          ...request,
+          mode: "oneshot",
+        });
+        const structuredContent = {
+          result: {
+            status: result.status,
+            text: result.text,
+            error: result.error,
+            taskId: result.taskId,
+          },
+          decision: result.decision,
+        };
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(structuredContent, null, 2),
+            },
+          ],
+          structuredContent,
+        };
+      } catch (err) {
+        if (err instanceof DelegationPolicyError) {
+          const structuredContent = {
+            result: {
+              status: "failed",
+              error: err.message,
+              taskId: request.taskId,
+            },
+            decision: err.decision,
+          };
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify(structuredContent, null, 2),
+              },
+            ],
+            structuredContent,
+          };
+        }
+        throw err;
+      }
+    },
+  );
+}

package/src/tools/explain.ts

@@ -0,0 +1,57 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  RouteRequestSchema,
+  routeRequest,
+  type RouteDecision,
+} from "offrouter-core";
+import { z } from "zod";
+import type { OffRouterMcpContext } from "../server.js";
+
+const inputSchema = {
+  route: RouteRequestSchema,
+};
+
+const outputSchema = {
+  decision: z.record(z.unknown()),
+  explanation: z.string(),
+};
+
+/**
+ * offrouter_explain_decision — same scoring path as route, named for harness
+ * agents that want an explicit explain call.
+ */
+export function registerExplainDecisionTool(
+  server: McpServer,
+  context: OffRouterMcpContext,
+): void {
+  server.registerTool(
+    "offrouter_explain_decision",
+    {
+      title: "OffRouter explain decision",
+      description:
+        "Explain why OffRouter would choose (or block) a route for the given request.",
+      inputSchema,
+      outputSchema,
+    },
+    async (args) => {
+      const decision: RouteDecision = routeRequest(
+        args.route,
+        context.candidates,
+        context.policy,
+      );
+      const structuredContent = {
+        decision,
+        explanation: decision.explanation,
+      };
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(structuredContent, null, 2),
+          },
+        ],
+        structuredContent,
+      };
+    },
+  );
+}

package/src/tools/route.ts

@@ -0,0 +1,49 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  RouteRequestSchema,
+  routeRequest,
+  type RouteDecision,
+} from "offrouter-core";
+import { z } from "zod";
+import type { OffRouterMcpContext } from "../server.js";
+
+const inputSchema = {
+  route: RouteRequestSchema,
+};
+
+const outputSchema = {
+  decision: z.record(z.unknown()),
+};
+
+export function registerRouteTool(
+  server: McpServer,
+  context: OffRouterMcpContext,
+): void {
+  server.registerTool(
+    "offrouter_route",
+    {
+      title: "OffRouter route",
+      description:
+        "Select a model route for a request using OffRouter policy and ranking. Uses prompt digest/preview only.",
+      inputSchema,
+      outputSchema,
+    },
+    async (args) => {
+      const decision: RouteDecision = routeRequest(
+        args.route,
+        context.candidates,
+        context.policy,
+      );
+      const structuredContent = { decision };
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(structuredContent, null, 2),
+          },
+        ],
+        structuredContent,
+      };
+    },
+  );
+}

package/src/tools/status.ts

@@ -0,0 +1,74 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { OffRouterMcpContext } from "../server.js";
+
+const inputSchema = {};
+
+const outputSchema = {
+  status: z.object({
+    configuredProfiles: z.array(z.string()),
+    configuredProviders: z.array(z.string()),
+    registeredAdapters: z.array(z.string()),
+    invokableProviders: z.array(z.string()),
+    configuredButNotInvokableProviders: z.array(z.string()),
+    candidateCount: z.number().int().nonnegative(),
+    activeTasks: z.number().int().nonnegative(),
+  }),
+};
+
+export function registerStatusTool(
+  server: McpServer,
+  context: OffRouterMcpContext,
+): void {
+  server.registerTool(
+    "offrouter_status",
+    {
+      title: "OffRouter status",
+      description:
+        "Report configured profiles/providers and active in-process delegation task count for this MCP server.",
+      inputSchema,
+      outputSchema,
+    },
+    async () => {
+      const activeTasks = context.runtime
+        .listTasks()
+        .filter((t) => t.status === "running" || t.status === "queued").length;
+      const registeredAdapters = Object.keys(context.adapters).sort((a, b) =>
+        a.localeCompare(b),
+      );
+      const candidateProviders = new Set(
+        context.candidates.map((candidate) => candidate.providerId),
+      );
+      const invokableProviders = registeredAdapters.filter((providerId) =>
+        candidateProviders.has(providerId),
+      );
+      const invokable = new Set(invokableProviders);
+      const configuredButNotInvokableProviders =
+        context.configuredProviders.filter(
+          (providerId) => !invokable.has(providerId),
+        );
+
+      const structuredContent = {
+        status: {
+          configuredProfiles: [...context.configuredProfiles],
+          configuredProviders: [...context.configuredProviders],
+          registeredAdapters,
+          invokableProviders,
+          configuredButNotInvokableProviders,
+          candidateCount: context.candidates.length,
+          activeTasks,
+        },
+      };
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(structuredContent, null, 2),
+          },
+        ],
+        structuredContent,
+      };
+    },
+  );
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"],
+  "references": [{ "path": "../core" }]
+}