@grainulation/mill 1.0.0

package/lib/serve-mcp.js

@@ -0,0 +1,340 @@
+/**
+ * mill serve-mcp — Local MCP server for Claude Code
+ *
+ * Exposes format conversion tools over stdio.
+ * Zero npm dependencies.
+ *
+ * Tools:
+ *   mill/convert  — Convert compilation/claims to any of 23+ formats
+ *   mill/formats  — List all available export formats
+ *   mill/preview  — Preview a conversion without writing to disk
+ *
+ * Resources:
+ *   mill://formats — Full format catalog with descriptions and MIME types
+ *
+ * Install:
+ *   claude mcp add mill -- npx @grainulation/mill serve-mcp
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const SERVER_NAME = 'mill';
+const SERVER_VERSION = '1.0.0';
+const PROTOCOL_VERSION = '2024-11-05';
+
+const FORMATS_DIR = path.join(__dirname, 'formats');
+
+// ─── JSON-RPC helpers ───────────────────────────────────────────────────────
+
+function jsonRpcResponse(id, result) {
+  return JSON.stringify({ jsonrpc: '2.0', id, result });
+}
+
+function jsonRpcError(id, code, message) {
+  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+// ─── Format discovery ───────────────────────────────────────────────────────
+
+let _formatCache = null;
+
+async function discoverFormats() {
+  if (_formatCache) return _formatCache;
+
+  const formats = [];
+  try {
+    const files = fs.readdirSync(FORMATS_DIR).filter(f => f.endsWith('.js'));
+    for (const file of files) {
+      try {
+        const mod = await import(path.join(FORMATS_DIR, file));
+        formats.push({
+          id: file.replace('.js', ''),
+          name: mod.name || file.replace('.js', ''),
+          extension: mod.extension || '',
+          mimeType: mod.mimeType || 'text/plain',
+          description: mod.description || '',
+          convert: mod.convert,
+        });
+      } catch (err) {
+        process.stderr.write(`mill: skipping ${file}: ${err.message}\n`);
+      }
+    }
+  } catch {}
+
+  _formatCache = formats;
+  return formats;
+}
+
+// ─── Tool implementations ───────────────────────────────────────────────────
+
+async function toolConvert(dir, args) {
+  const { format, source, output } = args;
+  if (!format) {
+    return { status: 'error', message: 'Required field: format (e.g., "csv", "markdown", "json-ld")' };
+  }
+
+  const formats = await discoverFormats();
+  const fmt = formats.find(f => f.id === format || f.name === format);
+  if (!fmt) {
+    return { status: 'error', message: `Unknown format: "${format}". Use mill/formats to list available formats.` };
+  }
+  if (!fmt.convert) {
+    return { status: 'error', message: `Format "${format}" does not have a convert function.` };
+  }
+
+  // Resolve source file
+  const sourceFile = source || path.join(dir, 'compilation.json');
+  const fallbackFile = path.join(dir, 'claims.json');
+  let dataPath = sourceFile;
+
+  if (!fs.existsSync(dataPath)) {
+    if (fs.existsSync(fallbackFile)) {
+      dataPath = fallbackFile;
+    } else {
+      return { status: 'error', message: `No source file found. Tried: ${sourceFile}, ${fallbackFile}` };
+    }
+  }
+
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(dataPath, 'utf8'));
+  } catch (err) {
+    return { status: 'error', message: `Failed to parse ${dataPath}: ${err.message}` };
+  }
+
+  // Normalize: compilation.json uses resolved_claims, claims.json uses claims
+  // Use resolved_claims if claims is missing or empty
+  if (data.resolved_claims && (!data.claims || data.claims.length === 0)) {
+    data.claims = data.resolved_claims;
+  }
+  if (data.sprint_meta && !data.meta) {
+    data.meta = data.sprint_meta;
+  }
+
+
+  // Run conversion
+  let result;
+  try {
+    result = fmt.convert(data);
+  } catch (err) {
+    return { status: 'error', message: `Conversion failed: ${err.message}` };
+  }
+
+  // Write output if path provided
+  if (output) {
+    const outPath = path.resolve(dir, output);
+    const outDir = path.dirname(outPath);
+    if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(outPath, result);
+    return { status: 'ok', message: `Converted to ${format}. Written to ${outPath}`, format: fmt.id, outputPath: outPath, bytes: Buffer.byteLength(result) };
+  }
+
+  // Return inline (truncate large outputs)
+  const maxLen = 10000;
+  const truncated = result.length > maxLen;
+  return {
+    status: 'ok',
+    format: fmt.id,
+    mimeType: fmt.mimeType,
+    output: truncated ? result.slice(0, maxLen) + '\n\n... (truncated, use output parameter to write full file)' : result,
+    bytes: Buffer.byteLength(result),
+    truncated,
+  };
+}
+
+async function toolFormats() {
+  const formats = await discoverFormats();
+  return {
+    status: 'ok',
+    count: formats.length,
+    formats: formats.map(f => ({
+      id: f.id,
+      name: f.name,
+      extension: f.extension,
+      mimeType: f.mimeType,
+      description: f.description,
+    })),
+  };
+}
+
+async function toolPreview(dir, args) {
+  const { format, source, lines } = args;
+  if (!format) {
+    return { status: 'error', message: 'Required field: format' };
+  }
+
+  // Run the same conversion but only return first N lines
+  const result = await toolConvert(dir, { format, source });
+  if (result.status === 'error') return result;
+
+  const maxLines = lines || 30;
+  const outputLines = (result.output || '').split('\n');
+  const preview = outputLines.slice(0, maxLines).join('\n');
+  const hasMore = outputLines.length > maxLines;
+
+  return {
+    status: 'ok',
+    format: result.format,
+    preview,
+    totalLines: outputLines.length,
+    showing: Math.min(maxLines, outputLines.length),
+    hasMore,
+  };
+}
+
+// ─── Tool & Resource definitions ────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'mill/convert',
+    description: 'Convert sprint compilation or claims to any supported format (csv, markdown, json-ld, yaml, sql, ndjson, html-report, executive-summary, slide-deck, jira-csv, github-issues, obsidian, graphml, dot, and more). Returns the converted output inline or writes to a file.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        format: { type: 'string', description: 'Target format ID (e.g., "csv", "markdown", "json-ld", "yaml", "sql", "obsidian")' },
+        source: { type: 'string', description: 'Source file path (default: ./compilation.json, falls back to ./claims.json)' },
+        output: { type: 'string', description: 'Output file path. If omitted, returns content inline.' },
+      },
+      required: ['format'],
+    },
+  },
+  {
+    name: 'mill/formats',
+    description: 'List all available export formats with descriptions, file extensions, and MIME types.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'mill/preview',
+    description: 'Preview a format conversion — shows first N lines without writing to disk.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        format: { type: 'string', description: 'Target format ID' },
+        source: { type: 'string', description: 'Source file path (default: ./compilation.json)' },
+        lines: { type: 'number', description: 'Number of lines to preview (default: 30)' },
+      },
+      required: ['format'],
+    },
+  },
+];
+
+const RESOURCES = [
+  {
+    uri: 'mill://formats',
+    name: 'Format Catalog',
+    description: 'All available export formats with descriptions, extensions, and MIME types.',
+    mimeType: 'application/json',
+  },
+];
+
+// ─── Request handler ────────────────────────────────────────────────────────
+
+async function handleRequest(dir, method, params, id) {
+  switch (method) {
+    case 'initialize':
+      return jsonRpcResponse(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {}, resources: {} },
+        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+      });
+
+    case 'notifications/initialized':
+      return null;
+
+    case 'tools/list':
+      return jsonRpcResponse(id, { tools: TOOLS });
+
+    case 'tools/call': {
+      const toolName = params.name;
+      const toolArgs = params.arguments || {};
+      let result;
+
+      switch (toolName) {
+        case 'mill/convert':  result = await toolConvert(dir, toolArgs); break;
+        case 'mill/formats':  result = await toolFormats(); break;
+        case 'mill/preview':  result = await toolPreview(dir, toolArgs); break;
+        default:
+          return jsonRpcError(id, -32601, `Unknown tool: ${toolName}`);
+      }
+
+      return jsonRpcResponse(id, {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        isError: result.status === 'error',
+      });
+    }
+
+    case 'resources/list':
+      return jsonRpcResponse(id, { resources: RESOURCES });
+
+    case 'resources/read': {
+      if (params.uri === 'mill://formats') {
+        const formats = await discoverFormats();
+        const text = JSON.stringify(formats.map(f => ({
+          id: f.id, name: f.name, extension: f.extension, mimeType: f.mimeType, description: f.description,
+        })), null, 2);
+        return jsonRpcResponse(id, {
+          contents: [{ uri: params.uri, mimeType: 'application/json', text }],
+        });
+      }
+      return jsonRpcError(id, -32602, `Unknown resource: ${params.uri}`);
+    }
+
+    case 'ping':
+      return jsonRpcResponse(id, {});
+
+    default:
+      if (id === undefined || id === null) return null;
+      return jsonRpcError(id, -32601, `Method not found: ${method}`);
+  }
+}
+
+// ─── Stdio transport ────────────────────────────────────────────────────────
+
+function startServer(dir) {
+  const rl = readline.createInterface({ input: process.stdin, terminal: false });
+
+  if (process.stdout._handle && process.stdout._handle.setBlocking) {
+    process.stdout._handle.setBlocking(true);
+  }
+
+  let pending = 0;
+  let closing = false;
+
+  function maybeDrain() {
+    if (closing && pending === 0) process.exit(0);
+  }
+
+  rl.on('line', async (line) => {
+    if (!line.trim()) return;
+    let msg;
+    try { msg = JSON.parse(line); } catch {
+      process.stdout.write(jsonRpcError(null, -32700, 'Parse error') + '\n');
+      return;
+    }
+    pending++;
+    const response = await handleRequest(dir, msg.method, msg.params || {}, msg.id);
+    if (response !== null) process.stdout.write(response + '\n');
+    pending--;
+    maybeDrain();
+  });
+
+  rl.on('close', () => { closing = true; maybeDrain(); });
+
+  process.stderr.write(`mill MCP server v${SERVER_VERSION} ready on stdio\n`);
+  process.stderr.write(`  Formats dir: ${FORMATS_DIR}\n`);
+  process.stderr.write(`  Tools: ${TOOLS.length} | Resources: ${RESOURCES.length}\n`);
+}
+
+// ─── Entry point ────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  startServer(process.cwd());
+}
+
+async function run(dir) { startServer(dir); }
+
+module.exports = { startServer, handleRequest, TOOLS, RESOURCES, run };