Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

10.3 KB
Raw Blame
// Admin CRUD for registered MCP servers.
//
// Registration is deliberately admin-only: a registered server is an outbound
// HTTP destination every scope's agents can call, so it is governed like a
// model-provider credential, not like a personal connector.

import {
  isValidMcpServerId,
  type McpApprovalPolicy,
  type McpServer,
  type McpServerAuthMode,
} from "../../../mcp/mcp-server-store.ts";
import { isAccountType, PROVIDERS } from "../../../connectors/oauth.ts";
import { discoverOAuth, httpsUrl, parseScopes, type DiscoveredOAuth } from "../../../mcp/oauth-discovery.ts";
import { sendJson } from "../../http.ts";
import type { ApiCtx } from "../route.ts";
import { audit, authorizeAdmin, orgScope } from "../shared.ts";

const AUTH_MODES: McpServerAuthMode[] = ["none", "bearer", "client-credentials", "oauth-user"];
const APPROVAL_POLICIES: McpApprovalPolicy[] = ["annotations", "all", "none"];

async function actor(ctx: ApiCtx) {
  const scope = orgScope(ctx.deps);
  return authorizeAdmin(ctx, scope);
}

function redact(server: McpServer): Omit<McpServer, "bearerToken" | "clientSecret"> & {
  hasBearerToken: boolean;
  hasClientSecret: boolean;
} {
  const { bearerToken, clientSecret, ...rest } = server;
  return { ...rest, hasBearerToken: !!bearerToken, hasClientSecret: !!clientSecret };
}

export async function getMcpServers(ctx: ApiCtx): Promise<void> {
  const authorized = await actor(ctx);
  if (!authorized) return;
  if (!ctx.deps.mcpServers) return sendJson(ctx.res, 404, { error: "not_found" });
  audit(ctx.deps, {
    principalId: authorized.id,
    action: "mcp-servers.read",
    resource: "mcp-servers",
    scopeLabel: orgScope(ctx.deps),
  });
  const servers = await ctx.deps.mcpServers.list();
  return sendJson(ctx.res, 200, {
    servers: servers.map(redact),
    tools: ctx.deps.mcpToolService?.toolDefs().map(({ name, serverId, description, readOnly, needsApproval }) => ({
      name,
      serverId,
      description,
      readOnly,
      needsApproval,
    })),
  });
}

export async function putMcpServer(ctx: ApiCtx): Promise<void> {
  const authorized = await actor(ctx);
  if (!authorized) return;
  if (!ctx.deps.mcpServers) return sendJson(ctx.res, 404, { error: "not_found" });
  const id = ctx.params.id ?? "";
  if (!isValidMcpServerId(id)) {
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: "id must be 2-40 chars: lowercase letters, digits, hyphens, starting with a letter",
    });
  }
  const b = ctx.body as Partial<McpServer> & { validate?: boolean };
  const url = typeof b.url === "string" ? b.url.trim() : "";
  let parsed: URL;
  try {
    parsed = new URL(url);
  } catch {
    return sendJson(ctx.res, 400, { error: "bad_request", message: "url must be a valid URL" });
  }
  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
    return sendJson(ctx.res, 400, { error: "bad_request", message: "url must be http(s)" });
  }
  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: "url must not carry credentials, query, or fragment",
    });
  }
  const auth = (b.auth ?? "none") as McpServerAuthMode;
  if (!AUTH_MODES.includes(auth)) {
    return sendJson(ctx.res, 400, { error: "bad_request", message: `auth must be one of ${AUTH_MODES.join(", ")}` });
  }
  const existing = await ctx.deps.mcpServers.get(id);
  const approval = b.approval ?? existing?.approval ?? "annotations";
  if (!APPROVAL_POLICIES.includes(approval)) {
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: `approval must be one of ${APPROVAL_POLICIES.join(", ")}`,
    });
  }
  const oauthUser = auth === "oauth-user";
  const catalog = (b.catalog ?? existing?.catalog) === true;
  const attestActor = (b.attestActor ?? existing?.attestActor) === true;
  if ((catalog || attestActor) && oauthUser) {
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: "catalog and attestActor are not available with oauth-user auth",
    });
  }
  if (oauthUser && PROVIDERS[id]) {
    return sendJson(ctx.res, 400, { error: "bad_request", message: `id ${id} is reserved by a built-in connector` });
  }
  const credentialScope = oauthUser ? "per-user" : (b.credentialScope ?? existing?.credentialScope ?? "shared");
  if (credentialScope !== "shared" && credentialScope !== "per-user") {
    return sendJson(ctx.res, 400, { error: "bad_request", message: "credentialScope must be shared or per-user" });
  }
  if (
    attestActor &&
    (!catalog || credentialScope !== "shared" || (auth !== "bearer" && auth !== "client-credentials"))
  ) {
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message:
        "attestActor requires catalog, shared credentials, and bearer or client-credentials auth, so only QM can assert the person",
    });
  }
  const credentialHost = b.credentialHost ?? existing?.credentialHost ?? (oauthUser ? parsed.hostname : undefined);
  if (
    oauthUser &&
    typeof credentialHost === "string" &&
    Object.values(PROVIDERS).some((p) =>
      p.hosts.some((h) => credentialHost === h || credentialHost.endsWith(`.${h}`) || h.endsWith(`.${credentialHost}`)),
    )
  ) {
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: "credentialHost is already used by another connector",
    });
  }
  for (const field of ["oauthAuthorizeUrl", "oauthTokenUrl"] as const) {
    if (oauthUser && b[field] !== undefined && !httpsUrl(b[field])) {
      return sendJson(ctx.res, 400, { error: "bad_request", message: `${field} must be an HTTPS URL` });
    }
  }
  let oauthAuthorizeUrl = httpsUrl(b.oauthAuthorizeUrl) ?? (oauthUser ? existing?.oauthAuthorizeUrl : undefined);
  let oauthTokenUrl = httpsUrl(b.oauthTokenUrl) ?? (oauthUser ? existing?.oauthTokenUrl : undefined);
  const credentialAccountType = b.credentialAccountType ?? existing?.credentialAccountType ?? "default";
  if (!isAccountType(credentialAccountType)) {
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: "credentialAccountType must be default, personal, or company",
    });
  }
  if (
    credentialScope === "per-user" &&
    (typeof credentialHost !== "string" ||
      !credentialHost ||
      credentialHost !== credentialHost.trim() ||
      credentialHost.length > 253 ||
      /[\s/\\?#@]/.test(credentialHost))
  ) {
    return sendJson(ctx.res, 400, { error: "bad_request", message: "per-user credentials require a credentialHost" });
  }
  if (
    credentialScope === "per-user" &&
    parsed.protocol !== "https:" &&
    !["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname)
  ) {
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: "per-user credentials require HTTPS (except loopback)",
    });
  }
  let discovered: DiscoveredOAuth | undefined;
  if (oauthUser && (!oauthAuthorizeUrl || !oauthTokenUrl)) {
    discovered = await discoverOAuth(parsed);
    oauthAuthorizeUrl ??= discovered.authorize;
    oauthTokenUrl ??= discovered.token;
  }
  const server: McpServer = {
    id,
    name: typeof b.name === "string" && b.name.trim() ? b.name.trim().slice(0, 80) : id,
    url,
    auth,
    credentialScope,
    ...(credentialScope === "per-user" ? { credentialHost, credentialAccountType } : {}),
    ...(auth === "bearer"
      ? { bearerToken: typeof b.bearerToken === "string" && b.bearerToken ? b.bearerToken : existing?.bearerToken }
      : {}),
    ...(oauthUser
      ? {
          clientId: typeof b.clientId === "string" && b.clientId ? b.clientId.trim() : existing?.clientId,
          oauthAuthorizeUrl,
          oauthTokenUrl,
          oauthScopes: parseScopes(b.oauthScopes) ?? existing?.oauthScopes ?? discovered?.scopes ?? [],
        }
      : {}),
    ...(auth === "client-credentials"
      ? {
          clientId: typeof b.clientId === "string" && b.clientId ? b.clientId : existing?.clientId,
          clientSecret: typeof b.clientSecret === "string" && b.clientSecret ? b.clientSecret : existing?.clientSecret,
        }
      : {}),
    ...(approval === "annotations" ? {} : { approval }),
    ...(catalog ? { catalog } : {}),
    ...(attestActor ? { attestActor } : {}),
    readOnly: b.readOnly !== false,
    enabled: b.enabled !== false,
    updatedAt: Date.now(),
    updatedBy: authorized.id,
  };
  if (auth === "bearer" && !server.bearerToken) {
    return sendJson(ctx.res, 400, { error: "bad_request", message: "bearer auth requires bearerToken" });
  }
  if (auth === "client-credentials" && (!server.clientId || !server.clientSecret)) {
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message: "client-credentials auth requires clientId and clientSecret",
    });
  }
  if (oauthUser && (!server.clientId || !server.oauthAuthorizeUrl || !server.oauthTokenUrl)) {
    return sendJson(ctx.res, 400, {
      error: "bad_request",
      message:
        "oauth-user auth requires clientId plus HTTPS oauthAuthorizeUrl and oauthTokenUrl, or OAuth metadata to discover them" +
        (discovered?.errors.length ? ` (discovery: ${discovered.errors.join("; ")})` : ""),
    });
  }
  let toolNames: string[] | undefined;
  if (b.validate !== false && !oauthUser && ctx.deps.mcpToolService) {
    try {
      toolNames = await ctx.deps.mcpToolService.probe(server, authorized.id);
    } catch (e) {
      return sendJson(ctx.res, 400, {
        error: "unreachable",
        message: `tools/list against ${parsed.host} failed: ${e instanceof Error ? e.message : String(e)}`,
      });
    }
  }
  await ctx.deps.mcpServers.put(server);
  audit(ctx.deps, {
    principalId: authorized.id,
    action: "mcp-servers.update",
    resource: id,
    scopeLabel: orgScope(ctx.deps),
  });
  return sendJson(ctx.res, 200, { ok: true, server: redact(server), ...(toolNames ? { tools: toolNames } : {}) });
}

export async function deleteMcpServer(ctx: ApiCtx): Promise<void> {
  const authorized = await actor(ctx);
  if (!authorized) return;
  if (!ctx.deps.mcpServers) return sendJson(ctx.res, 404, { error: "not_found" });
  const id = ctx.params.id ?? "";
  if (!(await ctx.deps.mcpServers.get(id))) return sendJson(ctx.res, 404, { error: "not_found" });
  await ctx.deps.mcpServers.delete(id);
  audit(ctx.deps, {
    principalId: authorized.id,
    action: "mcp-servers.delete",
    resource: id,
    scopeLabel: orgScope(ctx.deps),
  });
  return sendJson(ctx.res, 200, { ok: true });
}