@slashfi/agents-sdk 0.1.0 → 0.2.0

package/src/server.ts

@@ -1,21 +1,28 @@
 /**
- * Agent Server
+ * Agent Server (MCP over HTTP)
  *
- * HTTP server that exposes the agent registry via JSON-RPC endpoints.
- * Compatible with MCP (Model Context Protocol) over HTTP.
+ * JSON-RPC server implementing the MCP protocol for agent interaction.
+ * Compatible with atlas-environments and any MCP client.
  *
- * Endpoints:
- * - POST /call - Execute agent actions (execute_tool, describe_tools, load)
- * - GET /list - List registered agents
- * - POST /oauth/token - OAuth2 token endpoint (when @auth is registered)
+ * MCP Methods:
+ * - initialize       → Protocol handshake
+ * - tools/list        → List available MCP tools (call_agent, list_agents)
+ * - tools/call        → Execute an MCP tool
+ *
+ * MCP Tools exposed:
+ * - call_agent   → Execute a tool on a registered agent
+ * - list_agents  → List registered agents and their tools
+ *
+ * Additional endpoints:
+ * - POST /oauth/token → OAuth2 client_credentials (when @auth registered)
+ * - GET /health       → Health check
  *
  * Auth Integration:
  * When an `@auth` agent is registered, the server automatically:
  * - Validates Bearer tokens on requests
  * - Resolves tokens to identity + scopes
- * - Populates callerId, callerType in the request context
+ * - Populates caller context from headers (X-Atlas-Actor-Id, etc.)
  * - Recognizes the root key for admin access
- * - Mounts the /oauth/token endpoint
  */
 
 import type { AuthStore } from "./auth.js";
@@ -26,45 +33,52 @@ import type { AgentDefinition, CallAgentRequest, Visibility } from "./types.js";
 // Server Types
 // ============================================
 
-/**
- * Server configuration options.
- */
 export interface AgentServerOptions {
   /** Port to listen on (default: 3000) */
   port?: number;
-
   /** Hostname to bind to (default: 'localhost') */
   hostname?: string;
-
   /** Base path for endpoints (default: '') */
   basePath?: string;
-
   /** Enable CORS (default: true) */
   cors?: boolean;
-
-  /** Custom request handler for unmatched routes */
-  onNotFound?: (req: Request) => Response | Promise<Response>;
+  /** Server name reported in MCP initialize (default: 'agents-sdk') */
+  serverName?: string;
+  /** Server version reported in MCP initialize (default: '1.0.0') */
+  serverVersion?: string;
 }
 
-/**
- * Agent server instance.
- */
 export interface AgentServer {
   /** Start the server */
   start(): Promise<void>;
-
   /** Stop the server */
   stop(): Promise<void>;
-
   /** Handle a request (for custom integrations) */
   fetch(req: Request): Promise<Response>;
-
   /** Get the server URL (only available after start) */
   url: string | null;
 }
 
 // ============================================
-// Auth Integration Types
+// JSON-RPC Types
+// ============================================
+
+interface JsonRpcRequest {
+  jsonrpc?: string;
+  id?: unknown;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+interface JsonRpcResponse {
+  jsonrpc: string;
+  id: unknown;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+// ============================================
+// Auth Types
 // ============================================
 
 interface AuthConfig {
@@ -81,15 +95,13 @@ interface ResolvedAuth {
 }
 
 // ============================================
-// Response Helpers
+// Helpers
 // ============================================
 
 function jsonResponse(data: unknown, status = 200): Response {
   return new Response(JSON.stringify(data), {
     status,
-    headers: {
-      "Content-Type": "application/json",
-    },
+    headers: { "Content-Type": "application/json" },
   });
 }
 
@@ -97,7 +109,34 @@ function corsHeaders(): Record<string, string> {
   return {
     "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-    "Access-Control-Allow-Headers": "Content-Type, Authorization",
+    "Access-Control-Allow-Headers":
+      "Content-Type, Authorization, X-Atlas-Actor-Id, X-Atlas-Agent-Id, X-Atlas-Session-Id",
+  };
+}
+
+function jsonRpcSuccess(id: unknown, result: unknown): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function jsonRpcError(
+  id: unknown,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, error: { code, message, ...(data !== undefined && { data }) } };
+}
+
+/** Wrap a value as MCP tool result content */
+function mcpResult(value: unknown, isError = false) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof value === "string" ? value : JSON.stringify(value, null, 2),
+      },
+    ],
+    ...(isError && { isError: true }),
   };
 }
 
@@ -133,23 +172,14 @@ async function resolveAuth(
   const [scheme, credential] = authHeader.split(" ", 2);
   if (scheme?.toLowerCase() !== "bearer" || !credential) return null;
 
-  // Check root key
   if (credential === authConfig.rootKey) {
-    return {
-      callerId: "root",
-      callerType: "system",
-      scopes: ["*"],
-      isRoot: true,
-    };
+    return { callerId: "root", callerType: "system", scopes: ["*"], isRoot: true };
   }
 
-  // Validate token
   const token = await authConfig.store.validateToken(credential);
   if (!token) return null;
 
-  // Look up client name
   const client = await authConfig.store.getClient(token.clientId);
-
   return {
     callerId: client?.name ?? token.clientId,
     callerType: "agent",
@@ -158,42 +188,71 @@ async function resolveAuth(
   };
 }
 
-// ============================================
-// Visibility Filtering for /list
-// ============================================
-
-function canSeeAgent(
-  agent: AgentDefinition,
-  auth: ResolvedAuth | null,
-): boolean {
-  const visibility: Visibility = agent.visibility ?? "internal";
-
+function canSeeAgent(agent: AgentDefinition, auth: ResolvedAuth | null): boolean {
+  const visibility = (agent.config?.visibility ?? "internal") as Visibility;
   if (auth?.isRoot) return true;
   if (visibility === "public") return true;
   if (visibility === "internal" && auth) return true;
   return false;
 }
 
+// ============================================
+// MCP Tool Definitions
+// ============================================
+
+function getToolDefinitions() {
+  return [
+    {
+      name: "call_agent",
+      description:
+        "Execute a tool on a registered agent. Provide the agent path and tool name.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          request: {
+            type: "object",
+            description: "The call request",
+            properties: {
+              action: {
+                type: "string",
+                enum: ["execute_tool", "describe_tools", "load"],
+                description: "Action to perform",
+              },
+              path: {
+                type: "string",
+                description: "Agent path (e.g. '@registry')",
+              },
+              tool: {
+                type: "string",
+                description: "Tool name to call (for execute_tool)",
+              },
+              params: {
+                type: "object",
+                description: "Parameters for the tool",
+                additionalProperties: true,
+              },
+            },
+            required: ["action", "path"],
+          },
+        },
+        required: ["request"],
+      },
+    },
+    {
+      name: "list_agents",
+      description: "List all registered agents and their available tools.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+      },
+    },
+  ];
+}
+
 // ============================================
 // Create Server
 // ============================================
 
-/**
- * Create an HTTP server for the agent registry.
- *
- * @example
- * ```typescript
- * const registry = createAgentRegistry();
- * registry.register(createAuthAgent({ rootKey: 'rk_xxx' }));
- * registry.register(myAgent);
- *
- * const server = createAgentServer(registry, { port: 3000 });
- * await server.start();
- * // POST /call - Execute agent actions
- * // GET /list - List agents (filtered by auth)
- * // POST /oauth/token - OAuth2 token endpoint
- * ```
- */
 export function createAgentServer(
   registry: AgentRegistry,
   options: AgentServerOptions = {},
@@ -203,31 +262,210 @@ export function createAgentServer(
     hostname = "localhost",
     basePath = "",
     cors = true,
-    onNotFound,
+    serverName = "agents-sdk",
+    serverVersion = "1.0.0",
   } = options;
 
   let serverInstance: ReturnType<typeof Bun.serve> | null = null;
   let serverUrl: string | null = null;
 
-  // Detect auth configuration
   const authConfig = detectAuth(registry);
 
-  /**
-   * Handle incoming requests.
-   */
+  // ──────────────────────────────────────────
+  // MCP JSON-RPC handler
+  // ──────────────────────────────────────────
+
+  async function handleJsonRpc(
+    request: JsonRpcRequest,
+    auth: ResolvedAuth | null,
+  ): Promise<JsonRpcResponse> {
+    switch (request.method) {
+      // MCP protocol handshake
+      case "initialize":
+        return jsonRpcSuccess(request.id, {
+          protocolVersion: "2024-11-05",
+          capabilities: { tools: {} },
+          serverInfo: { name: serverName, version: serverVersion },
+        });
+
+      case "notifications/initialized":
+        return jsonRpcSuccess(request.id, {});
+
+      // List MCP tools
+      case "tools/list":
+        return jsonRpcSuccess(request.id, {
+          tools: getToolDefinitions(),
+        });
+
+      // Call an MCP tool
+      case "tools/call": {
+        const { name, arguments: args } = (request.params ?? {}) as {
+          name: string;
+          arguments?: Record<string, unknown>;
+        };
+
+        try {
+          const result = await handleToolCall(name, args ?? {}, auth);
+          return jsonRpcSuccess(request.id, result);
+        } catch (err) {
+          return jsonRpcSuccess(
+            request.id,
+            mcpResult(
+              `Error: ${err instanceof Error ? err.message : String(err)}`,
+              true,
+            ),
+          );
+        }
+      }
+
+      default:
+        return jsonRpcError(
+          request.id,
+          -32601,
+          `Method not found: ${request.method}`,
+        );
+    }
+  }
+
+  // ──────────────────────────────────────────
+  // MCP tool implementations
+  // ──────────────────────────────────────────
+
+  async function handleToolCall(
+    toolName: string,
+    args: Record<string, unknown>,
+    auth: ResolvedAuth | null,
+  ) {
+    switch (toolName) {
+      case "call_agent": {
+        const req = (args.request ?? args) as CallAgentRequest;
+
+        // Inject auth context
+        if (auth) {
+          req.callerId = auth.callerId;
+          req.callerType = auth.callerType;
+          if (!req.metadata) req.metadata = {};
+          req.metadata.scopes = auth.scopes;
+          req.metadata.isRoot = auth.isRoot;
+        }
+        if (auth?.isRoot) {
+          req.callerType = "system";
+        }
+
+        const result = await registry.call(req);
+        return mcpResult(result);
+      }
+
+      case "list_agents": {
+        const agents = registry.list();
+        const visible = agents.filter((agent) => canSeeAgent(agent, auth));
+
+        return mcpResult({
+          success: true,
+          agents: visible.map((agent) => ({
+            path: agent.path,
+            name: agent.config?.name,
+            description: agent.config?.description,
+            supportedActions: agent.config?.supportedActions,
+            tools: agent.tools
+              .filter((t) => {
+                const tv = t.visibility ?? "internal";
+                if (auth?.isRoot) return true;
+                if (tv === "public") return true;
+                if (tv === "internal" && auth) return true;
+                return false;
+              })
+              .map((t) => t.name),
+          })),
+        });
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${toolName}`);
+    }
+  }
+
+  // ──────────────────────────────────────────
+  // OAuth2 token handler (unchanged)
+  // ──────────────────────────────────────────
+
+  async function handleOAuthToken(req: Request): Promise<Response> {
+    if (!authConfig) {
+      return jsonResponse({ error: "auth_not_configured" }, 404);
+    }
+
+    const contentType = req.headers.get("Content-Type") ?? "";
+    let grantType: string;
+    let clientId: string;
+    let clientSecret: string;
+
+    if (contentType.includes("application/x-www-form-urlencoded")) {
+      const body = await req.text();
+      const params = new URLSearchParams(body);
+      grantType = params.get("grant_type") ?? "";
+      clientId = params.get("client_id") ?? "";
+      clientSecret = params.get("client_secret") ?? "";
+    } else {
+      const body = (await req.json()) as Record<string, string>;
+      grantType = body.grant_type ?? "";
+      clientId = body.client_id ?? "";
+      clientSecret = body.client_secret ?? "";
+    }
+
+    if (grantType !== "client_credentials") {
+      return jsonResponse(
+        { error: "unsupported_grant_type", error_description: "Only client_credentials is supported" },
+        400,
+      );
+    }
+
+    if (!clientId || !clientSecret) {
+      return jsonResponse(
+        { error: "invalid_request", error_description: "Missing client_id or client_secret" },
+        400,
+      );
+    }
+
+    const client = await authConfig.store.validateClient(clientId, clientSecret);
+    if (!client) {
+      return jsonResponse(
+        { error: "invalid_client", error_description: "Invalid client credentials" },
+        401,
+      );
+    }
+
+    const tokenString = `at_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+    const now = Date.now();
+
+    await authConfig.store.storeToken({
+      token: tokenString,
+      clientId: client.clientId,
+      scopes: client.scopes,
+      issuedAt: now,
+      expiresAt: now + authConfig.tokenTtl * 1000,
+    });
+
+    return jsonResponse({
+      access_token: tokenString,
+      token_type: "Bearer",
+      expires_in: authConfig.tokenTtl,
+      scope: client.scopes.join(" "),
+    });
+  }
+
+  // ──────────────────────────────────────────
+  // HTTP request handler
+  // ─��────────────────────────────────────────
+
   async function fetch(req: Request): Promise<Response> {
     const url = new URL(req.url);
     const path = url.pathname.replace(basePath, "") || "/";
 
-    // Handle CORS preflight
+    // CORS preflight
     if (cors && req.method === "OPTIONS") {
-      return new Response(null, {
-        status: 204,
-        headers: corsHeaders(),
-      });
+      return new Response(null, { status: 204, headers: corsHeaders() });
     }
 
-    // Add CORS headers to response
     const addCors = (response: Response): Response => {
       if (!cors) return response;
       const headers = new Headers(response.headers);
@@ -241,133 +479,30 @@ export function createAgentServer(
       });
     };
 
-    // Resolve auth on every request
     const auth = authConfig ? await resolveAuth(req, authConfig) : null;
 
     try {
-      // POST /oauth/token - Standard OAuth2 endpoint
-      if (path === "/oauth/token" && req.method === "POST" && authConfig) {
-        const contentType = req.headers.get("Content-Type") ?? "";
-        let grantType: string;
-        let clientId: string;
-        let clientSecret: string;
-
-        if (contentType.includes("application/x-www-form-urlencoded")) {
-          const body = await req.text();
-          const params = new URLSearchParams(body);
-          grantType = params.get("grant_type") ?? "";
-          clientId = params.get("client_id") ?? "";
-          clientSecret = params.get("client_secret") ?? "";
-        } else {
-          const body = (await req.json()) as Record<string, string>;
-          grantType = body.grant_type ?? "";
-          clientId = body.client_id ?? "";
-          clientSecret = body.client_secret ?? "";
-        }
-
-        if (grantType !== "client_credentials") {
-          return addCors(
-            jsonResponse(
-              {
-                error: "unsupported_grant_type",
-                error_description: "Only client_credentials is supported",
-              },
-              400,
-            ),
-          );
-        }
-
-        if (!clientId || !clientSecret) {
-          return addCors(
-            jsonResponse(
-              {
-                error: "invalid_request",
-                error_description: "Missing client_id or client_secret",
-              },
-              400,
-            ),
-          );
-        }
-
-        const client = await authConfig.store.validateClient(
-          clientId,
-          clientSecret,
-        );
-        if (!client) {
-          return addCors(
-            jsonResponse(
-              {
-                error: "invalid_client",
-                error_description: "Invalid client credentials",
-              },
-              401,
-            ),
-          );
-        }
-
-        // Generate token
-        const tokenString = `at_${Array.from({ length: 48 }, () => "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"[Math.floor(Math.random() * 62)]).join("")}`;
-        const token = {
-          token: tokenString,
-          clientId: client.clientId,
-          scopes: client.scopes,
-          issuedAt: Date.now(),
-          expiresAt: Date.now() + authConfig.tokenTtl * 1000,
-        };
-        await authConfig.store.storeToken(token);
-
-        // Standard OAuth2 response
-        return addCors(
-          jsonResponse({
-            access_token: token.token,
-            token_type: "bearer",
-            expires_in: authConfig.tokenTtl,
-            scope: client.scopes.join(" "),
-          }),
-        );
+      // MCP endpoint: POST / or POST /mcp
+      if ((path === "/" || path === "/mcp") && req.method === "POST") {
+        const body = (await req.json()) as JsonRpcRequest;
+        const response = await handleJsonRpc(body, auth);
+        return addCors(jsonResponse(response));
       }
 
-      // POST /call - Execute agent action
-      if (path === "/call" && req.method === "POST") {
-        const body = (await req.json()) as CallAgentRequest;
-
-        if (!body.path || !body.action) {
-          return addCors(
-            jsonResponse(
-              {
-                success: false,
-                error: "Missing required fields: path, action",
-                code: "INVALID_REQUEST",
-              },
-              400,
-            ),
-          );
-        }
-
-        // Inject auth context into request
-        if (auth) {
-          body.callerId = auth.callerId;
-          body.callerType = auth.callerType;
-          if (!body.metadata) body.metadata = {};
-          body.metadata.scopes = auth.scopes;
-          body.metadata.isRoot = auth.isRoot;
-        }
-
-        // Root key bypasses all access checks
-        if (auth?.isRoot) {
-          body.callerType = "system";
-        }
+      // OAuth2 token endpoint
+      if (path === "/oauth/token" && req.method === "POST") {
+        return addCors(await handleOAuthToken(req));
+      }
 
-        const result = await registry.call(body);
-        const status = "success" in result && result.success ? 200 : 400;
-        return addCors(jsonResponse(result, status));
+      // Health check
+      if (path === "/health" && req.method === "GET") {
+        return addCors(jsonResponse({ status: "ok" }));
       }
 
-      // GET /list - List agents (filtered by visibility)
+      // Backwards compat: GET /list (returns agents directly)
       if (path === "/list" && req.method === "GET") {
         const agents = registry.list();
         const visible = agents.filter((agent) => canSeeAgent(agent, auth));
-
         return addCors(
           jsonResponse({
             success: true,
@@ -390,55 +525,37 @@ export function createAgentServer(
         );
       }
 
-      // Not found
-      if (onNotFound) {
-        return addCors(await onNotFound(req));
-      }
-
-      return addCors(
-        jsonResponse(
-          {
-            success: false,
-            error: `Not found: ${req.method} ${path}`,
-            code: "NOT_FOUND",
-          },
-          404,
-        ),
-      );
+      return addCors(jsonResponse({ jsonrpc: "2.0", id: null, error: { code: -32601, message: `Not found: ${req.method} ${path}` } }, 404));
     } catch (err) {
       return addCors(
         jsonResponse(
-          {
-            success: false,
-            error: err instanceof Error ? err.message : String(err),
-            code: "INTERNAL_ERROR",
-          },
+          { jsonrpc: "2.0", id: null, error: { code: -32603, message: "Internal error" } },
           500,
         ),
       );
     }
   }
 
+  // ──────────────────────────────────────────
+  // Server lifecycle
+  // ──────────────────────────────────────────
+
   const server: AgentServer = {
     async start(): Promise<void> {
-      if (serverInstance) {
-        throw new Error("Server is already running");
-      }
-
-      serverInstance = Bun.serve({
-        port,
-        hostname,
-        fetch,
-      });
+      if (serverInstance) throw new Error("Server is already running");
 
+      serverInstance = Bun.serve({ port, hostname, fetch });
       serverUrl = `http://${hostname}:${port}${basePath}`;
+
       console.log(`Agent server running at ${serverUrl}`);
-      console.log(`  POST ${basePath}/call - Execute agent actions`);
-      console.log(`  GET  ${basePath}/list - List agents`);
+      console.log(`  POST /     - MCP JSON-RPC endpoint`);
+      console.log(`  POST /mcp  - MCP JSON-RPC endpoint (alias)`);
+      console.log(`  GET  /health - Health check`);
       if (authConfig) {
-        console.log(`  POST ${basePath}/oauth/token - OAuth2 token endpoint`);
-        console.log("  Auth: enabled (root key configured)");
+        console.log(`  POST /oauth/token - OAuth2 token endpoint`);
+        console.log("  Auth: enabled");
       }
+      console.log(`  MCP tools: call_agent, list_agents`);
     },
 
     async stop(): Promise<void> {