@husar.ai/cli 0.2.14 → 0.3.2

package/src/mcp.ts

@@ -2,73 +2,144 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
 import { z } from 'zod';
 import { ConfigMaker } from 'config-maker';
-import { spawn } from 'node:child_process';
+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';
 
 const server = new McpServer({ name: 'mcp-husar', version: '1.0.0' });
 
-let config: ConfigMaker<{ host: string; adminToken: string }> | undefined;
-
-const getWorkspaceRoot = async (): Promise<string> => {
-  const envRoot = process.env.WORKSPACE_ROOT;
-  if (envRoot) return envRoot;
-  let cur = process.cwd();
-  for (let i = 0; i < 10; i++) {
-    try {
-      const pkgPath = path.join(cur, 'package.json');
-      const st = await fs.stat(pkgPath);
-      if (st.isFile()) {
-        const txt = await fs.readFile(pkgPath, 'utf8');
-        const pkg = JSON.parse(txt) as { workspaces?: unknown };
-        if (pkg && Object.prototype.hasOwnProperty.call(pkg, 'workspaces')) return cur;
+// 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 } } }
       }
-    } catch {
-      /* empty */
+      directives { name description locations args { name description type { kind name ofType { kind name ofType { kind name } } } defaultValue } }
     }
-    const parent = path.dirname(cur);
-    if (parent === cur) break;
-    cur = parent;
   }
-  return process.cwd();
-};
+`;
 
-const resolveWorkspacePath = async (p: string): Promise<string> => {
-  if (path.isAbsolute(p)) return p;
-  const root = await getWorkspaceRoot();
-  return path.resolve(root, p);
-};
+// 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);
+}
 
-const getConfig = async () => {
-  if (config) return config;
-  const root = await getWorkspaceRoot();
-  config = new ConfigMaker<{ host: string; adminToken: string }>('husar', {
-    decoders: {},
-    pathToProject: root,
-  });
-  return config;
-};
+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;
+}
 
-const getAuth = async () => {
-  const envHost = process.env.HUSAR_MCP_HOST;
-  const envToken = process.env.HUSAR_MCP_ADMIN_TOKEN;
-  if (envHost && envToken) return { host: envHost, adminToken: envToken } as const;
+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);
+}
 
-  // Non-interactive: read current config values only
-  try {
-    const cfg = await getConfig();
-    const { host, adminToken } = cfg.get();
-    if (host && adminToken) return { host, adminToken } as const;
-  } catch {
-    // ignore; we'll throw below
+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 };
+}
 
-  throw new Error(
-    'Missing HUSAR_MCP_HOST and/or HUSAR_MCP_ADMIN_TOKEN. Provide via env or husar.json in workspace root. ' +
-      (await getWorkspaceRoot()),
-  );
+const getConfig = async (pathToProject?: string) => {
+  return new ConfigMaker<HusarConfigType>('husar', {
+    decoders: {},
+    pathToProject,
+  });
 };
 
 const cmsParseFileInputFields = {
@@ -89,6 +160,12 @@ const cmsParseFileInputFields = {
     .describe(
       'Optional CMS name. Must not contain dashes (-). Prefer lowercase with underscores (e.g., examples_contactform). Defaults to the filename (lowercased).',
     ),
+  workspaceRoot: z
+    .string()
+    .optional()
+    .describe(
+      'Target folder for where husar.json is located. Needed when run in monorepo where husar.json is located in child repo',
+    ),
 };
 
 const cmsParseFileInputSchema = z.object(cmsParseFileInputFields);
@@ -135,37 +212,33 @@ const redirectConsoleToStderr = () => {
   };
 };
 
-const runCli = async (args: string[], workspaceCwd: string) => {
-  const npxBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-  return await new Promise<{ code: number; stdout: string; stderr: string }>((resolve) => {
-    const child = spawn(npxBin, ['-y', '@husar.ai/cli', ...args], {
-      cwd: workspaceCwd,
-      stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env },
-      shell: false,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (d) => (stdout += String(d)));
-    child.stderr.on('data', (d) => (stderr += String(d)));
-    child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
-  });
-};
-
 const createCmsParseFileHandler = ({ timeoutMs = 30_000 }: { timeoutMs?: number }) => {
-  return async ({ path: file, type, name: passed }: CmsParseFileInput) => {
+  return async ({ path: file, type, name: passed, workspaceRoot }: CmsParseFileInput) => {
     const restoreConsole = redirectConsoleToStderr();
     try {
-      // Ensure config exists or env is set; if missing, CLI will error
-      await getAuth();
-      const absPath = await resolveWorkspacePath(file);
-      const root = await getWorkspaceRoot();
-      const name = (passed ?? (absPath.replace(/^.*\/(.*?)(\.[^.]+)?$/, '$1') || 'untitled')).toLowerCase();
-      const res = await withTimeout(runCli(['copy', absPath, name, '-t', type ?? 'shape'], root), timeoutMs);
-      if (res.code !== 0) {
-        throw new Error(`CLI exited with code ${res.code}.\nSTDOUT:\n${res.stdout}\nSTDERR:\n${res.stderr}`);
+      const cfg = await getConfig(workspaceRoot);
+      const raw = cfg.get();
+      const inputFile = stripWorkspaceRoot(file, workspaceRoot);
+      const name = (passed ?? (inputFile.replace(/^.*\/(.*?)(\.[^.]+)?$/, '$1') || 'untitled')).toLowerCase();
+      if (!raw.host) {
+        throw new Error('Please implement host in husar.json');
       }
-      return { content: [{ type: 'text', text: res.stdout || 'ok' }] };
+      if (!raw.adminToken) {
+        throw new Error('Please implement adminToken in husar.json');
+      }
+      const result = await withTimeout(
+        parser({
+          inputFile,
+          workspaceRoot,
+          opts: { type: (type ?? 'shape') as 'model' | 'shape', name },
+          authentication: {
+            HUSAR_MCP_HOST: raw.host,
+            HUSAR_MCP_ADMIN_TOKEN: raw.adminToken,
+          },
+        }),
+        timeoutMs,
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       const stack = err instanceof Error && err.stack ? `\nStack: ${err.stack}` : '';
@@ -181,14 +254,6 @@ const createCmsParseFileHandler = ({ timeoutMs = 30_000 }: { timeoutMs?: number
 };
 
 export const startMcpServer = async () => {
-  // Tool: cms_parse_file (legacy)
-  server.tool(
-    'cms_parse_file',
-    'Parse a CMS file into a shape or model',
-    cmsParseFileInputFields,
-    createCmsParseFileHandler({ timeoutMs: Number(process.env.MCP_PARSER_TIMEOUT_MS || 30000) }) as any,
-  );
-
   // Tool: husar_copy (alias)
   server.tool(
     'husar_copy',
@@ -203,24 +268,34 @@ export const startMcpServer = async () => {
       .string()
       .optional()
       .describe('Target folder for cms scaffolding. Relative to workspace root; defaults to ".".'),
+    workspaceRoot: z
+      .string()
+      .optional()
+      .describe(
+        'Target folder for where husar.json is located. Needed when run in monorepo where husar.json is located in child repo',
+      ),
   } as const;
   const husarGenerateSchema = z.object(husarGenerateInput);
+
   server.tool('husar_generate', 'Generate cms structure in the given path', husarGenerateInput, (async (
     args: unknown,
   ) => {
     try {
-      const { folderPath } = husarGenerateSchema.parse(args ?? {});
-      const root = await getWorkspaceRoot();
-      // Ensure config exists; if missing, CLI will error
-      await getAuth();
-      const argsList = ['generate'];
-      if (folderPath) argsList.push(folderPath);
-      const res = await runCli(argsList, root);
-      if (res.code !== 0) {
-        throw new Error(`CLI exited with code ${res.code}.\nSTDOUT:\n${res.stdout}\nSTDERR:\n${res.stderr}`);
+      const { folderPath = './src', workspaceRoot } = husarGenerateSchema.parse(args ?? {});
+      const cfg = await getConfig(workspaceRoot);
+      const raw = cfg.get();
+      const host = raw.host;
+      if (!host) {
+        throw new Error('Missing host. Provide via husar.json (host) or HUSAR_MCP_HOST/HUSAR_HOST env.');
       }
-      // The CLI doesn't print a JSON payload; return a simple ok message
-      return { content: [{ type: 'text', text: res.stdout || 'ok' }] };
+      const base = workspaceRoot ? path.join(workspaceRoot, folderPath) : folderPath;
+      const cmsPath = await generateCms({
+        baseFolder: base,
+        host,
+        hostEnvironmentVariable: (raw as any).hostEnvironmentVariable,
+        authenticationEnvironmentVariable: (raw as any).authenticationEnvironmentVariable,
+      });
+      return { content: [{ type: 'text', text: JSON.stringify({ status: 'ok', folder: cmsPath }, null, 2) }] };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       const stack = err instanceof Error && err.stack ? `\nStack: ${err.stack}` : '';
@@ -228,6 +303,385 @@ 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,
+  );
+
   const transport = new StdioServerTransport();
   server.connect(transport);
   try {
@@ -261,3 +715,29 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   // eslint-disable-next-line no-void
   void startMcpServer();
 }
+
+/**
+ * Removes the workspaceRoot prefix from filePath if filePath is within workspaceRoot.
+ * - Returns the path relative to workspaceRoot when included.
+ * - Returns filePath unchanged when it's outside workspaceRoot.
+ * - If filePath equals workspaceRoot, returns an empty string.
+ */
+export function stripWorkspaceRoot(filePath: string, workspaceRoot?: string): string {
+  if (!workspaceRoot) return filePath;
+
+  const rootAbs = path.resolve(workspaceRoot);
+  const fileAbs = path.resolve(filePath);
+
+  const isWin = path.sep === '\\';
+  const rootCmp = isWin ? rootAbs.toLowerCase() : rootAbs;
+  const fileCmp = isWin ? fileAbs.toLowerCase() : fileAbs;
+
+  if (fileCmp === rootCmp) return '';
+
+  // Ensure fileAbs is inside rootAbs before using relative
+  if (fileCmp.startsWith(rootCmp + path.sep)) {
+    return path.relative(rootAbs, fileAbs);
+  }
+
+  return filePath;
+}