@husar.ai/cli 0.3.0 → 0.3.3

package/src/mcp.ts

@@ -8,9 +8,137 @@ import { parser } from './functions/parser.js';
 import { generateCms } from './functions/generate.js';
 import path from 'path';
 import { HusarConfigType } from '@/types/config.js';
+import {
+  buildClientSchema,
+  printSchema,
+  buildSchema,
+  GraphQLSchema,
+  isObjectType,
+  getNamedType,
+  isNonNullType,
+  isListType,
+  GraphQLObjectType,
+} from 'graphql';
+import { getOrmToolSpecs } from '@husar.ai/genai';
 
 const server = new McpServer({ name: 'mcp-husar', version: '1.0.0' });
 
+// Minimal GraphQL introspection query compatible with GraphQL 16
+const INTROSPECTION_QUERY = `
+  query IntrospectionQuery {
+    __schema {
+      queryType { name }
+      mutationType { name }
+      subscriptionType { name }
+      types {
+        kind
+        name
+        description
+        fields(includeDeprecated: true) {
+          name
+          description
+          args { name description type { kind name ofType { kind name ofType { kind name } } } defaultValue }
+          type { kind name ofType { kind name ofType { kind name } } }
+          isDeprecated
+          deprecationReason
+        }
+        inputFields { name description type { kind name ofType { kind name ofType { kind name } } } defaultValue }
+        interfaces { kind name ofType { kind name ofType { kind name } } }
+        enumValues(includeDeprecated: true) { name description isDeprecated deprecationReason }
+        possibleTypes { kind name ofType { kind name ofType { kind name } } }
+      }
+      directives { name description locations args { name description type { kind name ofType { kind name ofType { kind name } } } defaultValue } }
+    }
+  }
+`;
+
+// Heuristic, local-only query suggester based on SDL and a text task
+function tokenize(s: string): string[] {
+  return (s || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, ' ')
+    .split(' ')
+    .filter(Boolean);
+}
+
+function scoreField(taskTokens: string[], fieldName: string, returnTypeName: string, argNames: string[]): number {
+  const nameTokens = tokenize(fieldName).concat(tokenize(returnTypeName)).concat(argNames.flatMap(tokenize));
+  let score = 0;
+  for (const t of taskTokens) if (nameTokens.includes(t)) score += 2;
+  // lightweight substring bonus
+  for (const t of taskTokens) if (fieldName.includes(t)) score += 1;
+  return score;
+}
+
+function pickFieldsForSelection(type: GraphQLObjectType): string[] {
+  const fields = Object.values(type.getFields());
+  const preferred = ['id', '_id', 'slug', 'name', 'title', 'key', 'display', 'createdAt', 'updatedAt'];
+  const names = fields.map((f) => f.name);
+  const out: string[] = [];
+  for (const p of preferred) if (names.includes(p)) out.push(p);
+  for (const n of names) if (out.length < 6 && !out.includes(n)) out.push(n);
+  return out.slice(0, 6);
+}
+
+function variablesTemplateFromArgs(args: readonly { name: string; type: unknown }[]): Record<string, unknown> {
+  const tmpl: Record<string, unknown> = {};
+  for (const a of args) tmpl[a.name] = null;
+  return tmpl;
+}
+
+function unwrapNamed(type: any): { named: any; list: boolean } {
+  let t = type;
+  let list = false;
+  while (isNonNullType(t) || isListType(t)) {
+    if (isListType(t)) list = true;
+    t = (t as any).ofType;
+  }
+  return { named: t, list };
+}
+
+function suggestQueryFromSDL({ sdl, task, rootType = 'Query' }: { sdl: string; task: string; rootType?: string }) {
+  const schema: GraphQLSchema = buildSchema(sdl);
+  const root = schema.getType(rootType);
+  if (!root || !isObjectType(root)) throw new Error(`Root type ${rootType} not found or not an object`);
+  const fields = Object.values(root.getFields());
+  const taskTokens = tokenize(task);
+  let best = fields[0];
+  let bestScore = -Infinity;
+  for (const f of fields) {
+    const { named } = unwrapNamed(f.type as any);
+    const retName = (named as any).name || '';
+    const s = scoreField(
+      taskTokens,
+      f.name,
+      retName,
+      f.args.map((a) => a.name),
+    );
+    if (s > bestScore) {
+      best = f;
+      bestScore = s;
+    }
+  }
+  const argsDecl = best.args.map((a) => `$${a.name}: ${(a.type as any).toString()}`).join(', ');
+  const argsUse = best.args.map((a) => `${a.name}: $${a.name}`).join(', ');
+  const { named, list } = unwrapNamed(best.type as any);
+  let selection = '__typename';
+  if (isObjectType(named)) {
+    const sel = pickFieldsForSelection(named as GraphQLObjectType);
+    selection = sel.join('\n          ');
+  }
+  const opName = 'GeneratedQuery';
+  const query = `query ${opName}${argsDecl ? `(${argsDecl})` : ''} {
+  ${best.name}${argsUse ? `(${argsUse})` : ''} {
+    ${list ? `nodes { ${selection} }` : selection}
+  }
+}`;
+  const variables = variablesTemplateFromArgs(best.args);
+  const candidates = fields
+    .map((f) => ({ name: f.name, type: (getNamedType(f.type as any) as any)?.name || String(f.type) }))
+    .slice(0, 20);
+  return { query, variables, pickedField: best.name, rootType, candidates };
+}
+
 const getConfig = async (pathToProject?: string) => {
   return new ConfigMaker<HusarConfigType>('husar', {
     decoders: {},
@@ -88,7 +216,7 @@ const redirectConsoleToStderr = () => {
   };
 };
 
-const createCmsParseFileHandler = ({ timeoutMs = 30_000 }: { timeoutMs?: number }) => {
+const createCmsParseFileHandler = ({ timeoutMs = 300_000 }: { timeoutMs?: number }) => {
   return async ({ path: file, type, name: passed, workspaceRoot }: CmsParseFileInput) => {
     const restoreConsole = redirectConsoleToStderr();
     try {
@@ -179,6 +307,422 @@ export const startMcpServer = async () => {
     }
   }) as any);
 
+  // Tool: husar_graphql_query (read-only helper)
+  const husarGraphQLQueryInput = {
+    query: z.string().min(1).describe('GraphQL query string.'),
+    variables: z
+      .union([z.string(), z.record(z.any())])
+      .optional()
+      .describe('Optional variables as JSON string or object.'),
+    endpointPath: z
+      .string()
+      .optional()
+      .default('api/graphql')
+      .describe('Endpoint path relative to host, defaults to api/graphql'),
+    workspaceRoot: z.string().optional().describe('Location of husar.json if not in current working directory.'),
+  } as const;
+  const husarGraphQLQuerySchema = z.object(husarGraphQLQueryInput);
+
+  server.tool(
+    'husar_graphql_query',
+    'Run a read-only GraphQL query against the configured Husar host',
+    husarGraphQLQueryInput,
+    (async (args: unknown) => {
+      try {
+        const { query, variables, endpointPath, workspaceRoot } = husarGraphQLQuerySchema.parse(args ?? {});
+        const cfg = await getConfig(workspaceRoot);
+        const raw = cfg.get();
+        const host = raw.host;
+        const token = raw.adminToken;
+        if (!host) throw new Error('Missing host in husar.json');
+        if (!token) throw new Error('Missing adminToken in husar.json');
+        const url = new URL(endpointPath || 'api/graphql', host).toString();
+        const vars =
+          typeof variables === 'string' && variables.trim().length ? JSON.parse(variables) : (variables ?? {});
+        const res = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', husar_token: token },
+          body: JSON.stringify({ query, variables: vars }),
+        });
+        const json = await res.json();
+        return { content: [{ type: 'text', text: JSON.stringify(json, null, 2) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const stack = err instanceof Error && err.stack ? `\nStack: ${err.stack}` : '';
+        return { isError: true, content: [{ type: 'text', text: `Error: ${message}${stack}` }] };
+      }
+    }) as any,
+  );
+
+  // Tool: husar_graphql_schema (admin)
+  const husarGraphQLSchemaInput = {
+    endpointPath: z
+      .string()
+      .optional()
+      .default('api/graphql')
+      .describe('Endpoint path relative to host, defaults to api/graphql'),
+    workspaceRoot: z.string().optional().describe('Location of husar.json if not in current working directory.'),
+  } as const;
+  const husarGraphQLSchemaSchema = z.object(husarGraphQLSchemaInput);
+
+  server.tool(
+    'husar_graphql_schema',
+    'Fetch GraphQL schema (introspection) from Admin API',
+    husarGraphQLSchemaInput,
+    (async (args: unknown) => {
+      try {
+        const { endpointPath, workspaceRoot } = husarGraphQLSchemaSchema.parse(args ?? {});
+        const cfg = await getConfig(workspaceRoot);
+        const raw = cfg.get();
+        const host = raw.host;
+        const token = raw.adminToken;
+        if (!host) throw new Error('Missing host in husar.json');
+        if (!token) throw new Error('Missing adminToken in husar.json');
+        const url = new URL(endpointPath || 'api/graphql', host).toString();
+        const res = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', husar_token: token },
+          body: JSON.stringify({ query: INTROSPECTION_QUERY }),
+        });
+        const json = await res.json();
+        return { content: [{ type: 'text', text: JSON.stringify(json, null, 2) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const stack = err instanceof Error && err.stack ? `\nStack: ${err.stack}` : '';
+        return { isError: true, content: [{ type: 'text', text: `Error: ${message}${stack}` }] };
+      }
+    }) as any,
+  );
+
+  // Tool: husar_graphql_schema_sdl (admin) — human-friendly SDL
+  server.tool('husar_graphql_schema_sdl', 'Fetch Admin GraphQL schema and return SDL', husarGraphQLSchemaInput, (async (
+    args: unknown,
+  ) => {
+    try {
+      const { endpointPath, workspaceRoot } = husarGraphQLSchemaSchema.parse(args ?? {});
+      const cfg = await getConfig(workspaceRoot);
+      const raw = cfg.get();
+      const host = raw.host;
+      const token = raw.adminToken;
+      if (!host) throw new Error('Missing host in husar.json');
+      if (!token) throw new Error('Missing adminToken in husar.json');
+      const url = new URL(endpointPath || 'api/graphql', host).toString();
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', husar_token: token },
+        body: JSON.stringify({ query: INTROSPECTION_QUERY }),
+      });
+      const json = await res.json();
+      if (!json?.data) throw new Error('No data from introspection');
+      const schema = buildClientSchema(json.data);
+      const sdl = printSchema(schema);
+      return { content: [{ type: 'text', text: sdl }] };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const stack = err instanceof Error && err.stack ? `\nStack: ${err.stack}` : '';
+      return { isError: true, content: [{ type: 'text', text: `Error: ${message}${stack}` }] };
+    }
+  }) as any);
+
+  // Tool: husar_content_graphql_query (read-only helper for Content API)
+  const husarContentGraphQLQueryInput = {
+    query: z.string().min(1).describe('GraphQL query string.'),
+    variables: z
+      .union([z.string(), z.record(z.any())])
+      .optional()
+      .describe('Optional variables as JSON string or object.'),
+    endpointPath: z
+      .string()
+      .optional()
+      .default('content/graphql')
+      .describe('Endpoint path relative to host, defaults to content/graphql'),
+    apiKey: z.string().optional().describe('Content API key. If omitted, apiKeyEnv is used.'),
+    apiKeyEnv: z.string().optional().describe('Environment variable name containing the Content API key.'),
+    workspaceRoot: z.string().optional().describe('Location of husar.json if not in current working directory.'),
+  } as const;
+  const husarContentGraphQLQuerySchema = z.object(husarContentGraphQLQueryInput);
+
+  server.tool(
+    'husar_content_graphql_query',
+    'Run a read-only GraphQL query against the Content API (api-key required)',
+    husarContentGraphQLQueryInput,
+    (async (args: unknown) => {
+      try {
+        const { query, variables, endpointPath, apiKey, apiKeyEnv, workspaceRoot } =
+          husarContentGraphQLQuerySchema.parse(args ?? {});
+        const cfg = await getConfig(workspaceRoot);
+        const raw = cfg.get();
+        const host = raw.host;
+        if (!host) throw new Error('Missing host in husar.json');
+        const keyFromEnv = apiKeyEnv ? process.env[apiKeyEnv] : undefined;
+        const keyFromConfig = (raw as any).contentApiKey as string | undefined;
+        const usedKey = apiKey || keyFromEnv || keyFromConfig;
+        if (!usedKey) throw new Error('Missing apiKey. Provide apiKey, apiKeyEnv, or set contentApiKey in husar.json');
+        const url = new URL(endpointPath || 'content/graphql', host).toString();
+        const vars =
+          typeof variables === 'string' && variables.trim().length ? JSON.parse(variables) : (variables ?? {});
+        const res = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'api-key': usedKey },
+          body: JSON.stringify({ query, variables: vars }),
+        });
+        const json = await res.json();
+        return { content: [{ type: 'text', text: JSON.stringify(json, null, 2) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const stack = err instanceof Error && err.stack ? `\nStack: ${err.stack}` : '';
+        return { isError: true, content: [{ type: 'text', text: `Error: ${message}${stack}` }] };
+      }
+    }) as any,
+  );
+
+  // Tool: husar_content_graphql_schema (content)
+  const husarContentGraphQLSchemaInput = {
+    endpointPath: z
+      .string()
+      .optional()
+      .default('content/graphql')
+      .describe('Endpoint path relative to host, defaults to content/graphql'),
+    apiKey: z.string().optional().describe('Content API key. If omitted, apiKeyEnv is used.'),
+    apiKeyEnv: z.string().optional().describe('Environment variable name containing the Content API key.'),
+    workspaceRoot: z.string().optional().describe('Location of husar.json if not in current working directory.'),
+  } as const;
+  const husarContentGraphQLSchemaSchema = z.object(husarContentGraphQLSchemaInput);
+
+  server.tool(
+    'husar_content_graphql_schema',
+    'Fetch GraphQL schema (introspection) from Content API',
+    husarContentGraphQLSchemaInput,
+    (async (args: unknown) => {
+      try {
+        const { endpointPath, apiKey, apiKeyEnv, workspaceRoot } = husarContentGraphQLSchemaSchema.parse(args ?? {});
+        const cfg = await getConfig(workspaceRoot);
+        const raw = cfg.get();
+        const host = raw.host;
+        if (!host) throw new Error('Missing host in husar.json');
+        const keyFromEnv = apiKeyEnv ? process.env[apiKeyEnv] : undefined;
+        const keyFromConfig = (raw as any).contentApiKey as string | undefined;
+        const usedKey = apiKey || keyFromEnv || keyFromConfig;
+        if (!usedKey) throw new Error('Missing apiKey. Provide apiKey, apiKeyEnv, or set contentApiKey in husar.json');
+        const url = new URL(endpointPath || 'content/graphql', host).toString();
+        const res = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'api-key': usedKey },
+          body: JSON.stringify({ query: INTROSPECTION_QUERY }),
+        });
+        const json = await res.json();
+        return { content: [{ type: 'text', text: JSON.stringify(json, null, 2) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const stack = err instanceof Error && err.stack ? `\nStack: ${err.stack}` : '';
+        return { isError: true, content: [{ type: 'text', text: `Error: ${message}${stack}` }] };
+      }
+    }) as any,
+  );
+
+  // Tool: husar_content_graphql_schema_sdl (content) — human-friendly SDL
+  server.tool(
+    'husar_content_graphql_schema_sdl',
+    'Fetch Content GraphQL schema and return SDL',
+    husarContentGraphQLSchemaInput,
+    (async (args: unknown) => {
+      try {
+        const { endpointPath, apiKey, apiKeyEnv, workspaceRoot } = husarContentGraphQLSchemaSchema.parse(args ?? {});
+        const cfg = await getConfig(workspaceRoot);
+        const raw = cfg.get();
+        const host = raw.host;
+        if (!host) throw new Error('Missing host in husar.json');
+        const keyFromEnv = apiKeyEnv ? process.env[apiKeyEnv] : undefined;
+        const keyFromConfig = (raw as any).contentApiKey as string | undefined;
+        const usedKey = apiKey || keyFromEnv || keyFromConfig;
+        if (!usedKey) throw new Error('Missing apiKey. Provide apiKey, apiKeyEnv, or set contentApiKey in husar.json');
+        const url = new URL(endpointPath || 'content/graphql', host).toString();
+        const res = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'api-key': usedKey },
+          body: JSON.stringify({ query: INTROSPECTION_QUERY }),
+        });
+        const json = await res.json();
+        if (!json?.data) throw new Error('No data from introspection');
+        const schema = buildClientSchema(json.data);
+        const sdl = printSchema(schema);
+        return { content: [{ type: 'text', text: sdl }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const stack = err instanceof Error && err.stack ? `\nStack: ${err.stack}` : '';
+        return { isError: true, content: [{ type: 'text', text: `Error: ${message}${stack}` }] };
+      }
+    }) as any,
+  );
+
+  // Tool: husar_graphql_suggest_query — given SDL + task, build a query
+  const husarSuggestInput = {
+    sdl: z.string().min(1).describe('GraphQL schema SDL'),
+    task: z.string().min(1).describe('Task description, e.g., "list posts by tag"'),
+    rootType: z.string().optional().default('Query'),
+  } as const;
+  const husarSuggestSchema = z.object(husarSuggestInput);
+
+  server.tool(
+    'husar_graphql_suggest_query',
+    'Suggest a GraphQL query and variables template from SDL + task',
+    husarSuggestInput,
+    (async (args: unknown) => {
+      try {
+        const { sdl, task, rootType } = husarSuggestSchema.parse(args ?? {});
+        const suggestion = suggestQueryFromSDL({ sdl, task, rootType });
+        return { content: [{ type: 'text', text: JSON.stringify(suggestion, null, 2) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const stack = err instanceof Error && err.stack ? `\nStack: ${err.stack}` : '';
+        return { isError: true, content: [{ type: 'text', text: `Error: ${message}${stack}` }] };
+      }
+    }) as any,
+  );
+
+  // Tool: husar_graphql_run_suggestion — suggest and run (Admin API)
+  const husarRunSuggestionInput = {
+    sdl: z.string().min(1).describe('GraphQL schema SDL'),
+    task: z.string().min(1).describe('Task to execute'),
+    variables: z
+      .union([z.string(), z.record(z.any())])
+      .optional()
+      .describe('Override variables (JSON)'),
+    endpointPath: z.string().optional().default('api/graphql'),
+    workspaceRoot: z.string().optional(),
+  } as const;
+  const husarRunSuggestionSchema = z.object(husarRunSuggestionInput);
+
+  server.tool(
+    'husar_graphql_run_suggestion',
+    'Generate a query from SDL + task and run it on Admin API',
+    husarRunSuggestionInput,
+    (async (args: unknown) => {
+      try {
+        const { sdl, task, variables, endpointPath, workspaceRoot } = husarRunSuggestionSchema.parse(args ?? {});
+        const cfg = await getConfig(workspaceRoot);
+        const raw = cfg.get();
+        const host = raw.host;
+        const token = raw.adminToken;
+        if (!host) throw new Error('Missing host in husar.json');
+        if (!token) throw new Error('Missing adminToken in husar.json');
+        const { query, variables: tmpl } = suggestQueryFromSDL({ sdl, task, rootType: 'Query' });
+        const overrides =
+          typeof variables === 'string' && variables.trim().length ? JSON.parse(variables) : (variables ?? {});
+        const merged = { ...tmpl, ...overrides };
+        const url = new URL(endpointPath || 'api/graphql', host).toString();
+        const res = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', husar_token: token },
+          body: JSON.stringify({ query, variables: merged }),
+        });
+        const json = await res.json();
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ query, variables: merged, result: json }, null, 2) }],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const stack = err instanceof Error && err.stack ? `\nStack: ${err.stack}` : '';
+        return { isError: true, content: [{ type: 'text', text: `Error: ${message}${stack}` }] };
+      }
+    }) as any,
+  );
+
+  // Tool: husar_content_graphql_run_suggestion — suggest and run (Content API)
+  const husarContentRunSuggestionInput = {
+    sdl: z.string().min(1).describe('GraphQL schema SDL'),
+    task: z.string().min(1).describe('Task to execute'),
+    variables: z
+      .union([z.string(), z.record(z.any())])
+      .optional()
+      .describe('Override variables (JSON)'),
+    endpointPath: z.string().optional().default('content/graphql'),
+    apiKey: z.string().optional().describe('Content API key'),
+    apiKeyEnv: z.string().optional().describe('Env var name containing Content API key'),
+    workspaceRoot: z.string().optional(),
+  } as const;
+  const husarContentRunSuggestionSchema = z.object(husarContentRunSuggestionInput);
+
+  server.tool(
+    'husar_content_graphql_run_suggestion',
+    'Generate a query from SDL + task and run it on Content API',
+    husarContentRunSuggestionInput,
+    (async (args: unknown) => {
+      try {
+        const { sdl, task, variables, endpointPath, apiKey, apiKeyEnv, workspaceRoot } =
+          husarContentRunSuggestionSchema.parse(args ?? {});
+        const cfg = await getConfig(workspaceRoot);
+        const raw = cfg.get();
+        const host = raw.host;
+        if (!host) throw new Error('Missing host in husar.json');
+        const keyFromEnv = apiKeyEnv ? process.env[apiKeyEnv] : undefined;
+        const keyFromConfig = (raw as any).contentApiKey as string | undefined;
+        const usedKey = apiKey || keyFromEnv || keyFromConfig;
+        if (!usedKey) throw new Error('Missing apiKey. Provide apiKey/apiKeyEnv or set contentApiKey in husar.json');
+        const { query, variables: tmpl } = suggestQueryFromSDL({ sdl, task, rootType: 'Query' });
+        const overrides =
+          typeof variables === 'string' && variables.trim().length ? JSON.parse(variables) : (variables ?? {});
+        const merged = { ...tmpl, ...overrides };
+        const url = new URL(endpointPath || 'content/graphql', host).toString();
+        const res = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'api-key': usedKey },
+          body: JSON.stringify({ query, variables: merged }),
+        });
+        const json = await res.json();
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ query, variables: merged, result: json }, null, 2) }],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const stack = err instanceof Error && err.stack ? `\nStack: ${err.stack}` : '';
+        return { isError: true, content: [{ type: 'text', text: `Error: ${message}${stack}` }] };
+      }
+    }) as any,
+  );
+
+  // Register Admin ORM tools so CLI MCP provides same toolset as Admin Agent
+  try {
+    const ormSpecs = getOrmToolSpecs();
+    const runAgentToolMutation = `mutation RunAgentTool($input: AgentToolRunInput!) {\n  admin {\n    runAgentTool(input: $input) { ok error executed result }\n  }\n}`;
+    for (const spec of ormSpecs) {
+      // We pass raw JSON Schema parameters to MCP server; SDK will forward as-is.
+      server.tool(spec.name, spec.description, spec.parameters, (async (args: unknown) => {
+        try {
+          const cfg = await getConfig(undefined);
+          const raw = cfg.get();
+          const host = raw.host;
+          const token = raw.adminToken;
+          if (!host) throw new Error('Missing host in husar.json');
+          if (!token) throw new Error('Missing adminToken in husar.json');
+          const url = new URL('api/graphql', host).toString();
+          const input = { name: spec.name, args };
+          const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', husar_token: token },
+            body: JSON.stringify({ query: runAgentToolMutation, variables: { input } }),
+          });
+          const json = await res.json();
+          const payload = json?.data?.admin?.runAgentTool ?? json;
+          // Ensure result is serializable text content for MCP
+          return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          const stack = err instanceof Error && err.stack ? `\nStack: ${err.stack}` : '';
+          return { isError: true, content: [{ type: 'text', text: `Error: ${message}${stack}` }] };
+        }
+      }) as any);
+    }
+  } catch (e) {
+    // In case tool spec import fails, keep MCP operational for other tools
+    const msg = e instanceof Error ? e.message : String(e);
+    try {
+      process.stderr.write(`[mcp] Failed to register ORM tools: ${msg}\n`);
+    } catch {
+      /* ignore */
+    }
+  }
+
   const transport = new StdioServerTransport();
   server.connect(transport);
   try {