@clarxai/mcp 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @clarxai/mcp
+
+Clarx MCP server — score agent manifests (`CLAUDE.md` / `AGENTS.md`), validate `clarx-manifest.json`, and generate Clarx CI workflows directly from your coding agent (Cursor, Claude Code, Claude Desktop, Windsurf, …).
+
+**No account required.** The core tools run entirely on your machine with the same rules as the [Clarx manifest studio](https://clarx.ai).
+
+## Setup
+
+Add to your MCP client config (e.g. `.cursor/mcp.json`, `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "clarx": {
+      "command": "npx",
+      "args": ["-y", "@clarxai/mcp@latest"]
+    }
+  }
+}
+```
+
+Claude Code:
+
+```bash
+claude mcp add clarx -- npx -y @clarxai/mcp@latest
+```
+
+## Tools
+
+| Tool | What it does | Requires |
+|------|--------------|----------|
+| `analyze_manifest` | Score a CLAUDE.md / AGENTS.md (0–100, pillar scores, findings with line numbers) | — |
+| `analyze_clarx_manifest` | Validate `clarx-manifest.json` against the engine schema | — |
+| `get_ci_workflow` | Generate a GitHub Actions workflow that gates PRs on the Clarx score | — |
+| `suggest_manifest_fix` | AI-write one manifest section to close a finding | `ANTHROPIC_API_KEY` |
+| `generate_manifest_draft` | AI-draft a full manifest from your README | `ANTHROPIC_API_KEY` |
+
+The AI tools are bring-your-own-key: set `ANTHROPIC_API_KEY` in the server `env` and they register automatically; without it they stay out of your agent's context.
+
+`analyze_manifest` scores are **manifest quality estimates** — the same rules the manifest studio uses. They are not comparable to Clarx repo AI-readiness scores, which come from a full engine scan.
+
+## Hosted mode (coming soon)
+
+Setting `CLARX_MCP_TOKEN` will unlock hosted tools — scan results, findings, and remediation prompts from your Clarx Cloud dashboard. Not available in this version.

package/dist/index.js

@@ -0,0 +1,648 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/local-tools.ts
+import { readFile } from "fs/promises";
+import { resolve } from "path";
+import { z } from "zod";
+
+// ../../packages/mcp-core/src/manifest-analyzer.ts
+var EXPECTED_SECTIONS = [
+  { key: "overview", label: "Project overview", pillar: "D", keywords: /(overview|introduction|about|what is|purpose)/i, minWords: 25, hint: "1-3 sentences. What is the product, who uses it, what problem does it solve." },
+  { key: "architecture", label: "Architecture & module map", pillar: "B", keywords: /(architecture|design|system|module|services?|deployable|topology)/i, minWords: 40, needsStructure: true, hint: "How the system is split. Name the deployable units and where each lives in the tree." },
+  { key: "build", label: "Build / install", pillar: "O", keywords: /(build|install|setup|getting started|run\b|dev server|develop)/i, minWords: 6, needsCode: true, hint: "The commands an agent runs to get a working environment. Show in a code block." },
+  { key: "testing", label: "Testing & verification", pillar: "O", keywords: /(test|verify|qa|spec\b|coverage)/i, minWords: 10, hint: "How to run tests + where they live. Mention the test runner." },
+  { key: "conventions", label: "Code conventions", pillar: "E", keywords: /(convention|style|standard|guideline|format|lint|rules?:)/i, minWords: 20, hint: "Naming, exports, imports, comments. The 'house rules' an agent should not violate." },
+  { key: "directory", label: "Directory structure", pillar: "D", keywords: /(director(y|ies)|file (tree|layout)|project structure|repo (layout|map))/i, minWords: 8, needsCode: true, hint: "A code-block tree of top-level folders with a 1-line gloss for each." },
+  { key: "entry", label: "Entry points / key files", pillar: "D", keywords: /(entry point|main file|where to start|key files?|important files?)/i, minWords: 10, hint: "Where to begin reading. Link 3-6 files an agent should open first." },
+  { key: "glossary", label: "Domain glossary", pillar: "E", keywords: /(glossary|terms?|vocabular|definitions|domain language)/i, minWords: 12, hint: "Domain words and their precise meaning in this codebase. Prevents misinterpretation." },
+  { key: "tasks", label: "Common tasks / recipes", pillar: "E", keywords: /(common tasks|how to|recipes?|workflow|playbook|how do i)/i, minWords: 15, hint: "Step-by-step for the 3-5 things an agent will be asked to do most often." },
+  { key: "deployment", label: "Deployment / ops", pillar: "O", keywords: /(deploy|production|release|ship|ci\/cd|pipeline|ops)/i, minWords: 10, hint: "How code reaches production. Branch model, deploy commands, environment names." },
+  { key: "apis", label: "External APIs & integrations", pillar: "B", keywords: /(api integrations?|external (service|api)|third.party|integrations?:)/i, minWords: 10, hint: "Outbound dependencies \u2014 names, why they're used, where credentials are configured." }
+];
+var PILLARS = [
+  { key: "D", name: "Discoverability", code: "D-rules" },
+  { key: "B", name: "Boundary clarity", code: "B-rules" },
+  { key: "C", name: "Context efficiency", code: "C-rules" },
+  { key: "O", name: "Operational guidance", code: "O-rules" },
+  { key: "E", name: "Edit safety", code: "E-rules" }
+];
+function parseHeaders(content) {
+  const lines = content.split("\n");
+  const headers = [];
+  let inCode = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^```/.test(line.trim())) {
+      inCode = !inCode;
+      continue;
+    }
+    if (inCode) continue;
+    const m = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (m) headers.push({ line: i + 1, level: m[1].length, title: m[2].trim() });
+  }
+  return headers;
+}
+function buildSections(content, headers) {
+  const lines = content.split("\n");
+  return headers.map((h, idx) => {
+    let endLine = lines.length;
+    for (let j = idx + 1; j < headers.length; j++) {
+      if (headers[j].level <= h.level) {
+        endLine = headers[j].line - 1;
+        break;
+      }
+    }
+    const body = lines.slice(h.line, endLine).join("\n");
+    return {
+      ...h,
+      endLine,
+      body,
+      words: body.replace(/```[\s\S]*?```/g, "").split(/\s+/).filter(Boolean).length,
+      hasCode: /```[\s\S]+?```/.test(body),
+      hasList: /^\s*[-*+]\s/m.test(body) || /^\s*\d+\.\s/m.test(body),
+      hasFileRef: /`[^`]*\.[a-zA-Z]{1,5}`|`[^`]*\/[^`]+`/.test(body)
+    };
+  });
+}
+function matchSection(sections, spec) {
+  for (const s of sections) if (spec.keywords.test(s.title)) return s;
+  for (const s of sections) {
+    if (spec.keywords.test(s.body)) return { ...s, matchedInBody: true };
+  }
+  return null;
+}
+function gradeSection(spec, match) {
+  if (!match) return { present: false, score: 0 };
+  let score = 1;
+  if (match.words < spec.minWords) score -= 0.4;
+  if (spec.needsCode && !match.hasCode) score -= 0.35;
+  if (spec.needsStructure && !match.hasList && !match.hasCode) score -= 0.25;
+  if (match.matchedInBody) score -= 0.3;
+  score = Math.max(0, Math.min(1, score));
+  const quality = score >= 0.8 ? "good" : score >= 0.45 ? "partial" : "weak";
+  return { present: true, score, quality, match };
+}
+function computePillarScores(checklist, content, headers) {
+  const lines = content.split("\n").length;
+  const byPillar = {};
+  for (const p of PILLARS) byPillar[p.key] = { num: 0, den: 0 };
+  for (const spec of EXPECTED_SECTIONS) {
+    const c = checklist[spec.key];
+    byPillar[spec.pillar].den += 1;
+    byPillar[spec.pillar].num += c.present ? c.score : 0;
+  }
+  let contextScore = 1;
+  if (lines < 40) contextScore = 0.45;
+  else if (lines < 90) contextScore = 0.7;
+  else if (lines > 700) contextScore = 0.45;
+  else if (lines > 500) contextScore = 0.7;
+  byPillar.C.num += contextScore;
+  byPillar.C.den += 1;
+  const hasH3 = headers.some((h) => h.level === 3);
+  if (hasH3) {
+    byPillar.D.num += 0.15;
+    byPillar.D.den += 0.15;
+  }
+  const out = {};
+  for (const p of PILLARS) {
+    const { num, den } = byPillar[p.key];
+    out[p.key] = den === 0 ? 0 : Math.round(num / den * 100);
+  }
+  return out;
+}
+var RULE_ID_MAP = {
+  overview: "D2",
+  architecture: "B1",
+  build: "O1",
+  testing: "O3",
+  conventions: "E1",
+  directory: "D5",
+  entry: "D3",
+  glossary: "E4",
+  tasks: "E2",
+  deployment: "O5",
+  apis: "B6"
+};
+function buildFindings(content, headers, sections, checklist) {
+  const findings = [];
+  let id = 1;
+  const ruleId = (pillar, key) => RULE_ID_MAP[key] ?? `${pillar}9`;
+  for (const spec of EXPECTED_SECTIONS) {
+    const c = checklist[spec.key];
+    if (!c.present) {
+      findings.push({ id: `F${id++}`, rule: ruleId(spec.pillar, spec.key), pillar: spec.pillar, severity: spec.key === "overview" || spec.key === "build" || spec.key === "architecture" ? "warn" : "info", line: 1, title: `Missing section: ${spec.label}`, desc: spec.hint, sectionKey: spec.key, actionable: true });
+      continue;
+    }
+    if (c.match?.matchedInBody) {
+      findings.push({ id: `F${id++}`, rule: ruleId(spec.pillar, spec.key), pillar: spec.pillar, severity: "info", line: c.match.line, title: `${spec.label} mentioned but not headlined`, desc: `Lift this content into its own \`## ${spec.label}\` section so agents can jump to it.`, sectionKey: spec.key });
+      continue;
+    }
+    if (c.match && c.match.words < spec.minWords) {
+      findings.push({ id: `F${id++}`, rule: ruleId(spec.pillar, spec.key), pillar: spec.pillar, severity: "warn", line: c.match.line, title: `${spec.label} is thin (${c.match.words} words)`, desc: `Expand to at least ${spec.minWords} words. ${spec.hint}`, sectionKey: spec.key });
+    }
+    if (spec.needsCode && c.match && !c.match.hasCode) {
+      findings.push({ id: `F${id++}`, rule: ruleId(spec.pillar, spec.key), pillar: spec.pillar, severity: "warn", line: c.match.line, title: `${spec.label} has no code block`, desc: "Include a runnable snippet (` ```bash \u2026 ``` `) so an agent can copy the command.", sectionKey: spec.key });
+    }
+  }
+  const lines = content.split("\n");
+  const lineCount = lines.length;
+  if (lineCount < 60) findings.push({ id: `F${id++}`, rule: "C3", pillar: "C", severity: "warn", line: 1, title: "Manifest is very short", desc: `Only ${lineCount} lines. An agent will guess at conventions you haven't stated.` });
+  else if (lineCount > 600) findings.push({ id: `F${id++}`, rule: "C1", pillar: "C", severity: "warn", line: 1, title: "Manifest is long (consumes context)", desc: `${lineCount} lines. Consider splitting subsystems into nested \`AGENTS.md\` files.` });
+  const todoRegex = /(TODO|FIXME|XXX)[:\s]/g;
+  for (let i = 0; i < lines.length; i++) {
+    if (todoRegex.test(lines[i])) findings.push({ id: `F${id++}`, rule: "E7", pillar: "E", severity: "info", line: i + 1, title: "Unresolved TODO marker", desc: "An agent will treat this as definitive. Resolve before shipping the manifest." });
+    todoRegex.lastIndex = 0;
+  }
+  for (const h of headers) {
+    if (h.level >= 5) findings.push({ id: `F${id++}`, rule: "D4", pillar: "D", severity: "info", line: h.line, title: "Heading nested 5+ levels deep", desc: `\`${"#".repeat(h.level)} ${h.title}\` \u2014 flatten or move into a sub-document.` });
+  }
+  if (!headers.some((h) => h.level === 1)) {
+    findings.push({ id: `F${id++}`, rule: "D1", pillar: "D", severity: "warn", line: 1, title: "Manifest has no top-level title (#)", desc: "Start with `# {Project name} \u2014 agent manifest` so agents anchor on identity." });
+  }
+  const sevOrder = { crit: 0, warn: 1, info: 2 };
+  findings.sort((a, b) => sevOrder[a.severity] - sevOrder[b.severity] || a.line - b.line);
+  return findings;
+}
+function analyze(content) {
+  const headers = parseHeaders(content);
+  const sections = buildSections(content, headers);
+  const checklist = {};
+  for (const spec of EXPECTED_SECTIONS) {
+    checklist[spec.key] = gradeSection(spec, matchSection(sections, spec));
+  }
+  const findings = buildFindings(content, headers, sections, checklist);
+  const pillars = computePillarScores(checklist, content, headers);
+  const overall = Math.round(PILLARS.reduce((acc, p) => acc + pillars[p.key], 0) / PILLARS.length);
+  const outline = headers.map((h) => ({ line: h.line, level: h.level, title: h.title }));
+  const lineCount = content.split("\n").length;
+  const wordCount = content.replace(/```[\s\S]*?```/g, "").split(/\s+/).filter(Boolean).length;
+  return { outline, findings, pillars, score: overall, checklist, stats: { lines: lineCount, words: wordCount, headers: headers.length } };
+}
+
+// ../../packages/mcp-core/src/ci-workflow.ts
+var DEFAULT_CLI_VERSION = "0.1.11";
+function buildCiWorkflowYaml(options) {
+  const {
+    minScore,
+    minPillarScore = null,
+    uploadSarif = false,
+    uploadArtifact = false,
+    cliVersion = DEFAULT_CLI_VERSION,
+    ignorePatterns = [],
+    useCompositeAction = false,
+    actionRef = "v1"
+  } = options;
+  const ignoreFlag = ignorePatterns.length > 0 ? ` --ignore '${ignorePatterns.join(",")}'` : "";
+  const permissionsBlock = uploadSarif ? `
+permissions:
+  contents: read
+  security-events: write
+` : "";
+  const scoreStep = useCompositeAction ? buildCompositeActionStep({ minScore, minPillarScore, uploadSarif, uploadArtifact, cliVersion, ignorePatterns, actionRef }) : buildNpxScoreSteps({ minScore, minPillarScore, uploadSarif, uploadArtifact, cliVersion, ignoreFlag });
+  return `# Generated by Clarx Cloud \u2014 clarx.ai/docs/ci
+name: Clarx
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+${permissionsBlock}
+jobs:
+  clarx:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+${scoreStep}
+`;
+}
+function buildCompositeActionStep(opts) {
+  const lines = [
+    `      - uses: clarxai/clarx-cloud/action@${opts.actionRef}`,
+    "        with:",
+    `          min-score: '${opts.minScore}'`
+  ];
+  if (opts.minPillarScore !== null) {
+    lines.push(`          min-pillar-score: '${opts.minPillarScore}'`);
+  }
+  if (opts.ignorePatterns.length > 0) {
+    lines.push(`          ignore: '${opts.ignorePatterns.join(",")}'`);
+  }
+  lines.push(`          cli-version: '${opts.cliVersion}'`);
+  if (opts.uploadSarif) lines.push(`          upload-sarif: 'true'`);
+  if (opts.uploadArtifact) lines.push(`          upload-artifact: 'true'`);
+  return lines.join("\n");
+}
+function buildNpxScoreSteps(opts) {
+  const pillarFlag = opts.minPillarScore !== null ? ` --min-pillar-score ${opts.minPillarScore}` : "";
+  const lines = [
+    "",
+    "      - uses: actions/setup-node@v4",
+    "        with:",
+    "          node-version: 22",
+    "",
+    "      - name: Score codebase",
+    `        run: npx @clarxai/cli@${opts.cliVersion} score . --ui text --min-score ${opts.minScore}${pillarFlag}${opts.ignoreFlag}`
+  ];
+  if (opts.uploadSarif) {
+    lines.push(
+      "",
+      "      - name: Generate SARIF",
+      "        if: always()",
+      `        run: npx @clarxai/cli@${opts.cliVersion} score . --format sarif${opts.ignoreFlag} > clarx.sarif`,
+      "",
+      "      - name: Upload SARIF",
+      "        if: always()",
+      "        uses: github/codeql-action/upload-sarif@v3",
+      "        with:",
+      "          sarif_file: clarx.sarif",
+      "          category: clarx"
+    );
+  }
+  if (opts.uploadArtifact) {
+    lines.push(
+      "",
+      "      - name: Markdown report",
+      "        if: always()",
+      `        run: npx @clarxai/cli@${opts.cliVersion} score . --format markdown${opts.ignoreFlag} > clarx-report.md`,
+      "",
+      "      - uses: actions/upload-artifact@v4",
+      "        if: always()",
+      "        with:",
+      "          name: clarx-report",
+      "          path: clarx-report.md"
+    );
+  }
+  return lines.join("\n");
+}
+
+// ../../packages/mcp-core/src/machine-manifest.ts
+var KNOWN_KEYS = ["generated", "highFanIn", "highFanOut", "verificationCommands", "commonTasks", "workspaces", "thresholds"];
+var KEY_HINTS = {
+  generated: "Directories agents should treat as build output, not source.",
+  highFanIn: "Files many modules import \u2014 agents edit these with extra care.",
+  highFanOut: "Known hub files (routers, registries) exempted from fan-out rules.",
+  verificationCommands: "How an agent verifies its changes. Closes O1 and unlocks the B-pillar.",
+  commonTasks: "Recipes for the changes agents are asked to make most often.",
+  workspaces: "Monorepo workspace roots.",
+  thresholds: "Per-repo overrides of engine defaults (e.g. maxFileLines). Rendered in rule messages."
+};
+function analyzeMachineManifest(content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (err) {
+    return { parseError: err instanceof Error ? err.message : "Invalid JSON", knownKeys: [], unknownKeys: [], thresholdIssues: [] };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { parseError: "Top level must be a JSON object.", knownKeys: [], unknownKeys: [], thresholdIssues: [] };
+  }
+  const obj = parsed;
+  const keys = Object.keys(obj);
+  const knownKeys = keys.filter((k) => KNOWN_KEYS.includes(k));
+  const unknownKeys = keys.filter((k) => !KNOWN_KEYS.includes(k));
+  const thresholdIssues = [];
+  if (obj.thresholds !== void 0) {
+    if (typeof obj.thresholds !== "object" || obj.thresholds === null || Array.isArray(obj.thresholds)) {
+      thresholdIssues.push("thresholds must be an object of numeric overrides.");
+    } else {
+      for (const [k, v] of Object.entries(obj.thresholds)) {
+        if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) {
+          thresholdIssues.push(`thresholds.${k} must be a finite positive number (got ${JSON.stringify(v)}).`);
+        }
+      }
+    }
+  }
+  return { parseError: null, knownKeys, unknownKeys, thresholdIssues };
+}
+
+// ../../packages/mcp-core/src/prompts.ts
+var MANIFEST_AI_MODEL = "claude-haiku-4-5-20251001";
+var MANIFEST_FIX_MAX_TOKENS = 800;
+var MANIFEST_DRAFT_MAX_TOKENS = 2500;
+function getSectionSpec(sectionKey) {
+  return EXPECTED_SECTIONS.find((s) => s.key === sectionKey);
+}
+function buildManifestFixPrompt(input) {
+  const {
+    sectionLabel,
+    hint,
+    pillar,
+    minWords,
+    needsCode,
+    needsStructure,
+    currentContent,
+    docPath,
+    repoName,
+    repoDescription,
+    repoReadme
+  } = input;
+  const system = `You are an expert at writing CLAUDE.md and AGENTS.md manifest files \u2014 structured documents that help AI coding agents understand a codebase.
+
+Your task is to write a single well-formed markdown section that fixes a specific quality issue.
+
+You must satisfy the validator exactly:
+- Return ONLY the raw markdown for one section, starting with ## or ###.
+- Use the requested section heading verbatim.
+- Include enough prose outside fenced code blocks to satisfy any minimum word count.
+- If a code block is required, include one.
+- If structure is required, include either a bullet list or a code block, and make the structure explicit.
+- Do not return placeholder text, generic advice, or commentary about what you are doing.`;
+  const repoContextLines = [];
+  if (repoName) repoContextLines.push(`**Repository name:** ${repoName}`);
+  if (repoDescription) repoContextLines.push(`**GitHub description:** ${repoDescription}`);
+  if (repoReadme) repoContextLines.push(`**README (excerpt):**
+\`\`\`
+${repoReadme.slice(0, 2500)}
+\`\`\``);
+  const repoContext = repoContextLines.length > 0 ? repoContextLines.join("\n") + "\n\n" : "";
+  const validatorRules = [
+    `Use the heading \`## ${sectionLabel}\` unless a \`###\` subsection is clearly more appropriate.`,
+    typeof minWords === "number" ? `Include at least ${minWords} words of prose outside fenced code blocks.` : null,
+    needsCode ? "Include at least one fenced code block in the section." : null,
+    needsStructure ? "Make the section structurally explicit with a bullet list or a code block." : null,
+    "Do not rely on a code block alone; include explanatory prose before and/or after it."
+  ].filter(Boolean).join("\n- ");
+  const user = `The manifest file at \`${docPath}\` has a quality issue:
+
+${repoContext}**Section needed:** ${sectionLabel} (pillar: ${pillar})
+**Guidance:** ${hint}
+**Validator rules:**
+- ${validatorRules}
+
+Here is the current full content of the manifest:
+\`\`\`markdown
+${currentContent.slice(0, 2e3)}
+\`\`\`
+
+Write the missing or improved \`## ${sectionLabel}\` section. Base it on the real repository information above \u2014 do not invent generic placeholder content. Keep it concise, but make sure it passes the validator rules above.`;
+  return { model: MANIFEST_AI_MODEL, maxTokens: MANIFEST_FIX_MAX_TOKENS, system, user };
+}
+function buildManifestDraftPrompt(input) {
+  const { filename, repoName, repoDescription, repoReadme } = input;
+  const agentName = filename.replace(/\.md$/i, "");
+  const system = `You are an expert at writing ${filename} manifest files \u2014 structured documents that teach AI coding agents how to work in a specific codebase.
+
+Write a complete first draft grounded ONLY in the repository information provided. Rules:
+- Return ONLY raw markdown, starting with \`# ${filename}\`.
+- Include these H2 sections in this order: Overview, Architecture, Build & Setup, Testing, Code conventions, Directory structure, Entry points.
+- Ground every claim in the README/description. Where the README does not say (e.g. exact test command), write a clearly-marked TODO line like \`<!-- TODO: confirm test command -->\` followed by your best inference \u2014 never invent specifics as fact.
+- Overview: 2-4 sentences on what the product is and who uses it.
+- Build & Setup and Directory structure must each include a fenced code block.
+- Keep the whole document under 120 lines. Concise and specific beats long and generic.`;
+  const contextLines = [];
+  if (repoName) contextLines.push(`**Repository:** ${repoName}`);
+  if (repoDescription) contextLines.push(`**Description:** ${repoDescription}`);
+  if (repoReadme) contextLines.push(`**README:**
+\`\`\`
+${repoReadme.slice(0, 6e3)}
+\`\`\``);
+  const user = `Draft ${filename} for this repository (guidance file for ${agentName} and similar AI agents):
+
+${contextLines.join("\n\n")}`;
+  return { model: MANIFEST_AI_MODEL, maxTokens: MANIFEST_DRAFT_MAX_TOKENS, system, user };
+}
+
+// src/anthropic.ts
+async function callAnthropic(prompt, apiKey) {
+  const res = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+      "content-type": "application/json"
+    },
+    body: JSON.stringify({
+      model: prompt.model,
+      max_tokens: prompt.maxTokens,
+      system: prompt.system,
+      messages: [{ role: "user", content: prompt.user }]
+    })
+  });
+  if (!res.ok) {
+    const err = await res.text().catch(() => "unknown error");
+    throw new Error(`Anthropic API error (${res.status}): ${err}`);
+  }
+  const data = await res.json();
+  const text = data.content?.find((b) => b.type === "text")?.text ?? "";
+  if (!text.trim()) throw new Error("No content returned from the model.");
+  return text;
+}
+
+// src/local-tools.ts
+function jsonResult(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+async function resolveContent(args) {
+  if (args.content !== void 0 && args.file_path !== void 0) {
+    return { error: "Pass exactly one of `content` or `file_path`, not both." };
+  }
+  if (args.content !== void 0) return { content: args.content, path: null };
+  if (args.file_path !== void 0) {
+    const abs = resolve(process.cwd(), args.file_path);
+    try {
+      return { content: await readFile(abs, "utf8"), path: args.file_path };
+    } catch (err) {
+      return { error: `Could not read ${abs}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+  return { error: "Pass one of `content` or `file_path`." };
+}
+function registerLocalTools(server2) {
+  server2.registerTool(
+    "analyze_manifest",
+    {
+      title: "Score an agent manifest",
+      description: "Score CLAUDE.md / AGENTS.md manifest content with the same rules as the Clarx manifest studio. Returns an overall quality estimate (0-100), per-pillar scores, findings with line numbers, and a section checklist. This is a manifest quality estimate \u2014 do not compare it to Clarx repo AI-readiness scores, which use a different rule system.",
+      inputSchema: {
+        content: z.string().optional().describe("Full markdown body of the manifest. Pass this or file_path, not both."),
+        file_path: z.string().optional().describe("Path to the manifest file (resolved against the server working directory, typically the workspace root). Preferred \u2014 avoids inlining the file into the conversation."),
+        include_outline: z.boolean().optional().default(true).describe("Include the heading outline (section tree with line numbers).")
+      }
+    },
+    async (args) => {
+      const resolved = await resolveContent(args);
+      if ("error" in resolved) return errorResult(resolved.error);
+      const result = analyze(resolved.content);
+      return jsonResult({
+        path: resolved.path,
+        line_count: result.stats.lines,
+        overall_score: result.score,
+        score_type: "manifest_quality_estimate",
+        pillar_scores: PILLARS.map((p) => ({ pillar: p.key, name: p.name, score: result.pillars[p.key] })),
+        findings: result.findings.map((f) => ({
+          id: f.id,
+          rule: f.rule,
+          pillar: f.pillar,
+          severity: f.severity,
+          line: f.line,
+          title: f.title,
+          description: f.desc,
+          section_key: f.sectionKey
+        })),
+        sections: EXPECTED_SECTIONS.map((spec) => {
+          const entry = result.checklist[spec.key];
+          return { key: spec.key, label: spec.label, present: entry.present, score: Math.round(entry.score * 100) };
+        }),
+        ...args.include_outline !== false ? { outline: result.outline } : {}
+      });
+    }
+  );
+  server2.registerTool(
+    "analyze_clarx_manifest",
+    {
+      title: "Validate clarx-manifest.json",
+      description: "Validate a clarx-manifest.json machine manifest against the Clarx engine schema. Returns recognized keys, errors, and suggestions for keys worth declaring (generated dirs, hubs, verification commands).",
+      inputSchema: {
+        content: z.string().optional().describe("Raw JSON content. Pass this or file_path, not both."),
+        file_path: z.string().optional().describe("Path to clarx-manifest.json (resolved against the server working directory).")
+      }
+    },
+    async (args) => {
+      const resolved = await resolveContent(args);
+      if ("error" in resolved) return errorResult(resolved.error);
+      const a = analyzeMachineManifest(resolved.content);
+      const errors = a.parseError ? [a.parseError] : [...a.thresholdIssues];
+      const suggestions = [];
+      if (!a.parseError) {
+        for (const k of a.unknownKeys) {
+          suggestions.push(`Remove or rename unknown key "${k}" \u2014 the engine ignores it. Valid keys: ${KNOWN_KEYS.join(", ")}.`);
+        }
+        for (const k of ["generated", "verificationCommands", "highFanIn", "highFanOut"]) {
+          if (!a.knownKeys.includes(k)) suggestions.push(`Consider adding "${k}": ${KEY_HINTS[k]}`);
+        }
+      }
+      return jsonResult({
+        valid: errors.length === 0,
+        errors,
+        keys_recognized: a.knownKeys,
+        suggestions
+      });
+    }
+  );
+  server2.registerTool(
+    "get_ci_workflow",
+    {
+      title: "Generate Clarx CI workflow",
+      description: "Generate a GitHub Actions workflow YAML that gates pull requests on the Clarx AI-readiness score (npx @clarxai/cli). Write the result to .github/workflows/clarx.yml.",
+      inputSchema: {
+        min_score: z.number().optional().default(80).describe("Fail the check when the overall score is below this (0-100)."),
+        min_pillar_score: z.number().nullable().optional().default(null).describe("Optional per-pillar floor."),
+        upload_sarif: z.boolean().optional().default(false).describe("Upload findings as SARIF to GitHub code scanning."),
+        upload_artifact: z.boolean().optional().default(true).describe("Attach a markdown report artifact to the run."),
+        ignore_patterns: z.array(z.string()).optional().default([]).describe("Glob patterns to exclude from scoring, e.g. ['vendor/**']."),
+        cli_version: z.string().optional().default(DEFAULT_CLI_VERSION).describe("@clarxai/cli version to pin.")
+      }
+    },
+    async (args) => {
+      const yaml = buildCiWorkflowYaml({
+        minScore: args.min_score ?? 80,
+        minPillarScore: args.min_pillar_score ?? null,
+        uploadSarif: args.upload_sarif ?? false,
+        uploadArtifact: args.upload_artifact ?? true,
+        ignorePatterns: args.ignore_patterns ?? [],
+        cliVersion: args.cli_version ?? DEFAULT_CLI_VERSION
+      });
+      return jsonResult({ filename: ".github/workflows/clarx.yml", yaml });
+    }
+  );
+  const anthropicKey = process.env.ANTHROPIC_API_KEY?.trim();
+  if (!anthropicKey) {
+    console.error("[clarx-mcp] ANTHROPIC_API_KEY not set \u2014 AI tools (suggest_manifest_fix, generate_manifest_draft) disabled.");
+    return;
+  }
+  server2.registerTool(
+    "suggest_manifest_fix",
+    {
+      title: "AI-write a manifest section",
+      description: "Write one well-formed markdown section of an agent manifest (CLAUDE.md / AGENTS.md) to close a finding from analyze_manifest. Uses your ANTHROPIC_API_KEY. Returns the section markdown to insert.",
+      inputSchema: {
+        section_key: z.string().describe(`Section to write. One of: ${EXPECTED_SECTIONS.map((s) => s.key).join(", ")}.`),
+        current_content: z.string().optional().describe("Current full manifest content for context (may be empty for a new file). Pass this or file_path."),
+        file_path: z.string().optional().describe("Read the current manifest from this path instead of inlining it."),
+        doc_path: z.string().optional().default("CLAUDE.md").describe("Manifest path used in the prompt, e.g. CLAUDE.md."),
+        repo_name: z.string().optional(),
+        repo_description: z.string().nullable().optional(),
+        repo_readme: z.string().nullable().optional().describe("README excerpt for grounding (max ~2500 chars used).")
+      }
+    },
+    async (args) => {
+      const spec = getSectionSpec(args.section_key);
+      if (!spec) {
+        return errorResult(`Unknown section_key "${args.section_key}". Valid keys: ${EXPECTED_SECTIONS.map((s) => s.key).join(", ")}.`);
+      }
+      let current = args.current_content;
+      let docPath = args.doc_path ?? "CLAUDE.md";
+      if (current === void 0 && args.file_path !== void 0) {
+        const resolved = await resolveContent({ file_path: args.file_path });
+        if ("error" in resolved) return errorResult(resolved.error);
+        current = resolved.content;
+        docPath = args.file_path;
+      }
+      if (current === void 0) return errorResult("Pass one of `current_content` or `file_path` (current_content may be an empty string for a new manifest).");
+      const prompt = buildManifestFixPrompt({
+        sectionLabel: spec.label,
+        hint: spec.hint,
+        pillar: spec.pillar,
+        minWords: spec.minWords,
+        needsCode: spec.needsCode,
+        needsStructure: spec.needsStructure,
+        currentContent: current,
+        docPath,
+        repoName: args.repo_name,
+        repoDescription: args.repo_description,
+        repoReadme: args.repo_readme
+      });
+      try {
+        const markdown = await callAnthropic(prompt, anthropicKey);
+        return jsonResult({ section_markdown: markdown, section_key: spec.key, pillar: spec.pillar });
+      } catch (err) {
+        return errorResult(err instanceof Error ? err.message : String(err));
+      }
+    }
+  );
+  server2.registerTool(
+    "generate_manifest_draft",
+    {
+      title: "AI-draft a full manifest",
+      description: "Generate a first-draft agent manifest (CLAUDE.md / AGENTS.md / GEMINI.md) grounded in the repository README and description. Uses your ANTHROPIC_API_KEY. Claims the model cannot ground are marked as TODO comments.",
+      inputSchema: {
+        filename: z.enum(["CLAUDE.md", "AGENTS.md", "GEMINI.md"]).describe("Manifest filename to draft."),
+        repo_name: z.string().optional(),
+        repo_description: z.string().nullable().optional(),
+        repo_readme: z.string().optional().describe("README content for grounding (max ~6000 chars used). Required unless repo_description is present.")
+      }
+    },
+    async (args) => {
+      if (!args.repo_readme && !args.repo_description) {
+        return errorResult("No repository context \u2014 pass repo_readme (preferred) or repo_description to draft from.");
+      }
+      const prompt = buildManifestDraftPrompt({
+        filename: args.filename,
+        repoName: args.repo_name,
+        repoDescription: args.repo_description,
+        repoReadme: args.repo_readme
+      });
+      try {
+        const markdown = await callAnthropic(prompt, anthropicKey);
+        return jsonResult({ filename: args.filename, markdown });
+      } catch (err) {
+        return errorResult(err instanceof Error ? err.message : String(err));
+      }
+    }
+  );
+}
+
+// src/index.ts
+var server = new McpServer({ name: "clarx", version: "0.1.0" });
+registerLocalTools(server);
+if (process.env.CLARX_MCP_TOKEN) {
+  console.error("[clarx-mcp] CLARX_MCP_TOKEN detected, but hosted tools are not available in this version. Local tools only.");
+}
+var transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[clarx-mcp] ready (stdio)");

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@clarxai/mcp",
+  "version": "0.1.0",
+  "description": "Clarx MCP server — score agent manifests, validate clarx-manifest.json, and generate CI workflows from your IDE. Set CLARX_MCP_TOKEN to unlock hosted scan data (coming soon).",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "clarx-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "clarx",
+    "ai-readiness",
+    "claude-md",
+    "agents-md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@clarxai/mcp-core": "workspace:^",
+    "@types/node": "^24.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3"
+  }
+}