Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

8.8 KB
Raw Blame
import type { Scope } from "./scope";
import type { McpTool } from "./tool-kit";

export type McpToolProfile = "full" | "chatgpt";
export type McpToolAnnotations = {
  readOnlyHint: boolean;
  destructiveHint: boolean;
  openWorldHint: boolean;
  idempotentHint?: boolean;
};
export type McpSecurityScheme = { type: "oauth2"; scopes: string[] } | { type: "noauth" };

/**
 * ChatGPT's scanner recommends output schemas for every tool that returns
 * structured data. Most MSO tools intentionally keep provider/project-specific
 * result shapes dynamic, so duplicating dozens of hand-maintained schemas would
 * create drift. The compact profile therefore uses one exact outer envelope for
 * tools without a richer explicit contract. `result` is the bounded JSON value
 * already produced by the tool. Full/generic MCP clients keep the historical
 * descriptor unless a tool declares its own outputSchema.
 */
export const CHATGPT_RESULT_OUTPUT_SCHEMA = {
  type: "object",
  properties: { result: {} },
  required: ["result"],
  additionalProperties: false,
} as const;

export function outputSchemaForProfile(tool: McpTool, profile: McpToolProfile = "full"): Record<string, unknown> | undefined {
  return tool.outputSchema ?? (profile === "chatgpt" ? CHATGPT_RESULT_OUTPUT_SCHEMA : undefined);
}

// ChatGPT should expose the complete MSO-owned generic model/operator catalog.
// Project-owned MCP tool names are never appended to TOOLS; they remain dynamic
// behind project_mcp_tools/project_mcp_call. These two compatibility bridges are
// UI-only and therefore intentionally excluded from model tool calling.
export const CHATGPT_APP_ONLY_TOOL_NAMES = new Set([
  "workflow_status",
  "render_mso_surface",
] as const);

const TITLES: Record<string, string> = {
  workflow_start: "Start Workflow", workflow_status: "Workflow Status", workflow_finish: "Finish Workflow", workflow_cancel: "Cancel Workflow",
  render_mso_list: "Render MSO List", render_mso_block: "Render MSO Block", render_mso_page: "Render MSO Page", render_mso_surface: "Render MSO Surface (Compatibility)",
  skills_search: "Search Skills", projects_list: "List Projects", project_capabilities: "Project Capabilities",
  project_mcp_tools: "List Project MCP Tools", project_mcp_call: "Call Project MCP Tool", project_function_call: "Call Project Function",
  read_pipeline: "Run Read Pipeline", fs_list: "List Files", fs_read: "Read File", fs_search: "Search Directories", fs_write: "Write File",
  exec_run: "Run Command", exec_job_start: "Start Command Job", exec_job_status: "Command Job Status", exec_job_cancel: "Cancel Command Job",
  agent_session_current: "Current Agent Session", agent_session_flow: "Read Session Flow", agent_session_action_resolve: "Resolve Session Action", agent_session_rename: "Rename Agent Session",
  local_agents_list: "List Local Agents", local_agent_inbox: "Receive Local Agent Messages", local_agent_standby: "Local Agent Standby",
  organization_chart: "Organization Chart", organization_manage: "Manage Organization",
  local_agent_message_send: "Send Local Agent Message", local_agent_reply: "Reply to Local Agent", local_agent_request_wait: "Wait for Local Agent Reply",
  a2a_agent_discover: "Discover A2A Agent", a2a_agents_list: "List A2A Agents", a2a_message_send: "Send A2A Message",
  cloudflare_dns_upsert: "Upsert Cloudflare DNS", hostinger_dns_upsert: "Upsert Hostinger DNS",
};
const ACRONYMS = new Map([["mcp", "MCP"], ["a2a", "A2A"], ["dns", "DNS"], ["fs", "Files"], ["api", "API"], ["ui", "UI"]]);

export function toolTitle(name: string): string {
  if (TITLES[name]) return TITLES[name];
  return name.split(/[_\.]+/).filter(Boolean).map((word) => ACRONYMS.get(word) ?? `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`).join(" ").slice(0, 80);
}

// Only declarations that can overwrite/delete/send/cancel or run arbitrary code
// need an override. Everything else inherits the safe scope-based default below.
const DESTRUCTIVE = new Set([
  "fs_write", "fs_upload_file", "fs_move", "fs_copy", "fs_delete",
  "exec_run", "exec_job_start", "exec_job_cancel", "project_function_call", "project_mcp_call",
  "local_agent_message_send", "local_agent_reply", "a2a_message_send", "a2a_task_cancel", "a2a_agent_remove",
  "dokploy_application_public_env_upsert", "cloudflare_dns_upsert", "hostinger_dns_upsert", "apps_power", "browser_power", "tool_forge_promote",
  "agent_memory_forget", "project_memory_upsert", "workflow_cancel",
]);

const OPEN_WORLD = new Set([
  "exec_run", "exec_job_start", "project_function_call", "project_mcp_call", "fs_upload_file",
  "a2a_agent_discover", "a2a_message_send", "a2a_task_get", "a2a_task_cancel", "a2a_handoff",
  "infra_provider_doctor", "dokploy_projects_list", "dokploy_applications_list", "dokploy_application_public_env_upsert", "dokploy_project_ensure", "cloudflare_zones_list",
  "cloudflare_dns_upsert", "hostinger_dns_upsert",
]);

export function completeToolAnnotations(tool: McpTool): McpToolAnnotations {
  const supplied = tool.annotations ?? {};
  return {
    readOnlyHint: typeof supplied.readOnlyHint === "boolean" ? supplied.readOnlyHint : tool.scope === "read",
    destructiveHint: typeof supplied.destructiveHint === "boolean" ? supplied.destructiveHint : DESTRUCTIVE.has(tool.name),
    openWorldHint: typeof supplied.openWorldHint === "boolean" ? supplied.openWorldHint : OPEN_WORLD.has(tool.name),
    ...(supplied.idempotentHint === true ? { idempotentHint: true } : {}),
  };
}

export function toolSecuritySchemes(tool: McpTool): McpSecurityScheme[] {
  return tool.securitySchemes ?? [{ type: "oauth2", scopes: [tool.scope] }];
}

export function actionContractForTool(tool: McpTool): Record<string, unknown> | undefined {
  if (!tool.actionContract) return undefined;
  return { version: 1, ...tool.actionContract };
}

export function toolAllowedForProfile(_name: string, _profile: McpToolProfile = "full"): boolean {
  return true;
}

function compactText(value: string, max = 80): string {
  const clean = value.replace(/\s+/g, " ").trim();
  if (clean.length <= max) return clean;
  const cut = clean.slice(0, max - 1);
  const sentence = Math.max(cut.lastIndexOf(". "), cut.lastIndexOf("; "));
  const word = clean[max - 1] === " " ? cut.length : cut.lastIndexOf(" ");
  const end = sentence > max * 0.8 ? sentence + 1 : word > max * 0.5 ? word : cut.length;
  return `${cut.slice(0, end).trim()}…`;
}

function compactSchema(value: unknown): unknown {
  if (Array.isArray(value)) return value.map(compactSchema);
  if (!value || typeof value !== "object") return value;
  const out: Record<string, unknown> = {};
  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
    if (key === "additionalProperties" && item === true || key === "required" && Array.isArray(item) && item.length === 0) continue;
    if (key === "workflow_id" && item && typeof item === "object") out[key] = { type:"string" };
    else if (key === "additionalProperties" && item && typeof item === "object") out[key] = true;
    else if (key === "items" && item && typeof item === "object" && (item as Record<string, unknown>).type === "object") { const row=compactSchema(item) as Record<string,unknown>; delete row.additionalProperties; out[key]=row; }
    else if (key === "description" || key === "title") continue;
    else out[key] = compactSchema(item);
  }
  return out;
}

const COMPACT_DESCRIPTIONS: Record<string, string> = {
  workflow_start: "First call: multi-step",
};

export function toolDescriptor(tool: McpTool, profile: McpToolProfile = "full") {
  const securitySchemes = toolSecuritySchemes(tool);
  // ChatGPT already receives the structured contract through published skill resources.
  // Keep action-level contracts on the full MCP descriptor so the compact ChatGPT
  // scanner stays below its deliberately strict byte budget without hiding any tools.
  const actionContract = profile === "full" ? actionContractForTool(tool) : undefined;
  const meta = { ...(tool.meta ?? {}), securitySchemes, ...(actionContract ? { "mso/actionContract": actionContract } : {}) };
  const compact = profile === "chatgpt";
  const outputSchema = outputSchemaForProfile(tool, profile);
  return {
    name: tool.name,
    title: tool.title ?? toolTitle(tool.name),
    description: compact ? compactText(COMPACT_DESCRIPTIONS[tool.name] ?? tool.chatgptDescription ?? tool.description, 24) : tool.description,
    inputSchema: compact ? compactSchema(tool.inputSchema) : tool.inputSchema,
    ...(outputSchema ? { outputSchema: compact ? compactSchema(outputSchema) : outputSchema } : {}),
    securitySchemes,
    annotations: completeToolAnnotations(tool),
    _meta: meta,
  };
}

export function visibleToolsForProfile(tools: readonly McpTool[], scope: Scope, profile: McpToolProfile = "full"): McpTool[] {
  const rank: Record<Scope, number> = { read: 0, write: 1, exec: 2 };
  return tools.filter((tool) => rank[scope] >= rank[tool.scope] && toolAllowedForProfile(tool.name, profile));
}