Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

18.5 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import { afterEach, describe, expect, it } from "vitest";

import {
  createIxMcpServer,
  IX_MCP_OSS_TOOL_NAMES,
  IX_MCP_PRO_TOOL_NAMES,
  IX_MCP_TOOL_NAMES,
  type IxRunner,
} from "../../mcp/server.js";

const clients: Client[] = [];

afterEach(async () => {
  await Promise.all(clients.splice(0).map((client) => client.close()));
});

async function connect(runIx: IxRunner, proAvailable = false): Promise<Client> {
  const server = createIxMcpServer({ version: "test", runIx, proAvailable, tools: "all" });
  // `all`, because these assertions are about the whole catalog. The core
  // default has its own tests in mcp-toolset.test.ts.
  const client = new Client({ name: "ix-mcp-test", version: "1.0.0" });
  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();

  await server.connect(serverTransport);
  await client.connect(clientTransport);
  clients.push(client);
  return client;
}

/**
 * A complete `ix-context-bundle/1`.
 *
 * `ix_context` declares an outputSchema, and the MCP SDK validates
 * structuredContent against it, so any stub short of a whole bundle comes back
 * as an output-validation error rather than a result. Tests that only meant to
 * assert on argv still need a valid one.
 */
function contextBundle() {
  return {
    schema: "ix-context-bundle/1",
    generatedAt: "2026-01-01T00:00:00Z",
    target: { id: "e1", name: "Widget", kind: "class", resolutionMode: "exact" },
    entities: [{ id: "e1", name: "Widget", kind: "class", stale: false }],
    relationships: [],
    claims: [],
    decisions: [],
    conflicts: [],
    intents: [],
    // buildBundle always emits these two (context.ts: `historyLength:
    // facts.historyLength` and `stale`), so an empty provenance is a bundle the
    // CLI cannot actually produce. The fixture has to be a bundle that could
    // come off the wire, or it proves nothing about the real contract.
    provenance: { historyLength: 0, stale: false },
    freshness: { stale: false, classification: "current" },
    evidence: [],
    budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 },
    truncation: { entitiesTruncated: 0, relationshipsTruncated: 0, evidenceTruncated: 0, charactersTruncated: 0 },
    metadata: { rankingRule: "deterministic-tier" },
  };
}

describe("ix mcp", () => {
  it("exposes only the OSS catalog when Pro is not installed", async () => {
    const client = await connect(async () => ({ ok: true, stdout: "ok", stderr: "" }));

    const result = await client.listTools();

    // Advertising a Pro tool on an OSS install hands the agent something whose
    // every call answers "requires Ix Pro" — indistinguishable from a failure.
    expect(result.tools.map((tool) => tool.name)).toEqual(IX_MCP_OSS_TOOL_NAMES);
    for (const pro of IX_MCP_PRO_TOOL_NAMES) {
      expect(result.tools.map((tool) => tool.name)).not.toContain(pro);
    }
  });

  it("adds the Pro catalog when Pro is installed", async () => {
    const client = await connect(async () => ({ ok: true, stdout: "ok", stderr: "" }), true);

    const result = await client.listTools();

    expect(result.tools.map((tool) => tool.name)).toEqual(IX_MCP_TOOL_NAMES);
  });

  it("covers every plugin tool that is not a composite or deprecated", async () => {
    const client = await connect(async () => ({ ok: true, stdout: "ok", stderr: "" }), true);
    const names = (await client.listTools()).tools.map((tool) => tool.name);

    // The union exposed by ix-codex/cursor/gemini/openclaw/opencode-plugin,
    // less ix_query (deprecated), ix_neighbors and ix_docs_tool (composites of
    // callers/callees/depends and of overview), and ix_status (gemini's name
    // for ix_health).
    for (const tool of ["ix_decide", "ix_ingest", "ix_health", "ix_locate", "ix_impact"]) {
      expect(names).toContain(tool);
    }
  });

  it("maps tool input to the matching Ix command with compact output", async () => {
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return { ok: true, stdout: "match name=Widget", stderr: "" };
    });

    const result = await client.callTool({
      name: "ix_locate",
      arguments: { symbol: "Widget" },
    });

    expect(calls).toEqual([["locate", "--format=llm", "--", "Widget"]]);
    expect(result.isError).toBeFalsy();
    expect(result.content).toEqual([{ type: "text", text: "match name=Widget" }]);
  });

  it("marks a structured LLM error as an MCP error when the CLI exits successfully", async () => {
    const error = 'error code=unresolved_target message="No graph entity found for \\"Missing\\"."';
    const client = await connect(async () => ({
      ok: true,
      stdout: error,
      stderr: 'No entity found matching "Missing".',
    }));

    const result = await client.callTool({
      name: "ix_locate",
      arguments: { symbol: "Missing" },
    });

    expect(result.isError).toBe(true);
    expect(result.content).toEqual([{ type: "text", text: error }]);
  });

  it("preserves a structured LLM error when the CLI exits non-zero", async () => {
    const error = 'error code=unresolved_target message="No graph entity found for \\"Missing\\"."';
    const client = await connect(async () => ({
      ok: false,
      stdout: error,
      stderr: 'No entity found matching "Missing".',
    }));

    const result = await client.callTool({
      name: "ix_impact",
      arguments: { target: "Missing" },
    });

    expect(result.isError).toBe(true);
    expect(result.content).toEqual([{ type: "text", text: error }]);
  });

  it("does not mistake arbitrary stdout from a failed command for a machine error", async () => {
    const client = await connect(async () => ({
      ok: false,
      stdout: "partial output",
      stderr: "backend unavailable",
    }));

    const result = await client.callTool({
      name: "ix_impact",
      arguments: { target: "Missing" },
    });

    expect(result.isError).toBe(true);
    expect(result.content).toEqual([{
      type: "text",
      text: JSON.stringify({ error: "backend unavailable", tool: "ix_impact" }),
    }]);
  });

  it("preserves a structured JSON error when the CLI exits non-zero", async () => {
    const error = JSON.stringify({ error: "invalid_map_path", message: "Path is outside the workspace." });
    const client = await connect(async () => ({
      ok: false,
      stdout: error,
      stderr: "Path is outside the workspace.",
    }));

    const result = await client.callTool({
      name: "ix_map",
      arguments: { file: "../outside.ts" },
    });

    expect(result.isError).toBe(true);
    expect(result.content).toEqual([{ type: "text", text: error }]);
  });

  it("keeps error-like source lines after a successful LLM record as data", async () => {
    const output = [
      "content target=fixture.ts lines=1",
      'error code=source_text message="This is source, not a tool error."',
    ].join("\n");
    const client = await connect(async () => ({ ok: true, stdout: output, stderr: "" }));

    const result = await client.callTool({
      name: "ix_read",
      arguments: { symbol: "fixture.ts" },
    });

    expect(result.isError).toBeFalsy();
    expect(result.content).toEqual([{ type: "text", text: output }]);
  });

  it("asks the CLI for records, and sends the bundle once", async () => {
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return { ok: true, stdout: "context target=Widget entities=2\nevidence score=0 kind=target title=Widget", stderr: "" };
    });

    const result = await client.callTool({
      name: "ix_context",
      arguments: { target: "Widget", max_entities: 20, max_evidence: 5 },
    });

    expect(result.isError).toBeFalsy();
    expect(calls).toEqual([
      ["context", "--max-entities=20", "--max-evidence=5", "--format=llm", "--", "Widget"],
    ]);
    // Once. The JSON text plus the same object again as structuredContent was
    // two copies of a bundle that can run to 20 KB.
    expect(result.structuredContent).toBeUndefined();
    expect(result.content).toEqual([
      { type: "text", text: "context target=Widget entities=2\nevidence score=0 kind=target title=Widget" },
    ]);
  });

  it("forwards ix_context max_chars to the CLI contract", async () => {
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return { ok: true, stdout: "context target=Widget", stderr: "" };
    });

    const result = await client.callTool({ name: "ix_context", arguments: { target: "Widget", max_evidence: 3, max_chars: 5000 } });

    expect(result.isError).toBeFalsy();
    expect(calls).toEqual([["context", "--max-evidence=3", "--max-chars=5000", "--format=llm", "--", "Widget"]]);
  });

  it("returns the JSON bundle as structuredContent when asked for it", async () => {
    const bundle = contextBundle();
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return { ok: true, stdout: JSON.stringify(bundle), stderr: "" };
    });

    const result = await client.callTool({ name: "ix_context", arguments: { target: "Widget", structured: true } });

    expect(calls).toEqual([["context", "--format=json", "--", "Widget"]]);
    const { generatedAt: _volatile, ...stable } = bundle;
    expect(result.structuredContent).toEqual(stable);
    expect(result.content).toEqual([{ type: "text", text: JSON.stringify(stable) }]);
  });

  it("two structured ix_context renders of the same input are byte-identical", async () => {
    const stamps = ["2026-01-01T00:00:00Z", "2026-01-01T00:00:05Z"];
    let n = 0;
    const client = await connect(async () => ({
      ok: true,
      stdout: JSON.stringify({ ...contextBundle(), generatedAt: stamps[n++] }),
      stderr: "",
    }));

    const args = { name: "ix_context", arguments: { target: "Widget", structured: true } };
    const r1 = await client.callTool(args);
    const r2 = await client.callTool(args);

    expect(JSON.stringify(r1)).toBe(JSON.stringify(r2));
    expect("generatedAt" in (r1.structuredContent as object)).toBe(false);
    expect(JSON.stringify(r1.content)).not.toContain("generatedAt");
  });

  it("keeps the structured text twin stable when stdout has a leading notice", async () => {
    const bundle = contextBundle();
    const outs = [
      `notice: update available\n${JSON.stringify({ ...bundle, generatedAt: "2026-01-01T00:00:00Z" })}`,
      JSON.stringify({ ...bundle, generatedAt: "2026-01-01T00:00:05Z" }),
    ];
    let n = 0;
    const client = await connect(async () => ({ ok: true, stdout: outs[n++], stderr: "" }));

    const args = { name: "ix_context", arguments: { target: "Widget", structured: true } };
    const r1 = await client.callTool(args);
    const r2 = await client.callTool(args);

    expect(r1.isError).toBeFalsy();
    expect(JSON.stringify(r1)).toBe(JSON.stringify(r2));
  });

  it("marks an unparseable bundle as an MCP error, on the structured path", async () => {
    const client = await connect(async () => ({ ok: true, stdout: "not json at all", stderr: "" }));

    const result = await client.callTool({ name: "ix_context", arguments: { target: "Widget", structured: true } });

    expect(result.isError).toBe(true);
    expect(result.structuredContent).toBeUndefined();
    expect(result.content).toEqual([{ type: "text", text: "not json at all" }]);
  });

  it("surfaces a CLI error record from the records path", async () => {
    const client = await connect(async () => ({
      ok: true,
      stdout: 'error code=unresolved_target message="No entity found matching \\"Widget\\"."',
      stderr: "",
    }));

    const result = await client.callTool({ name: "ix_context", arguments: { target: "Widget" } });

    expect(result.isError).toBe(true);
  });

  it("omits unset context budgets rather than sending empty flags", async () => {
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return { ok: true, stdout: "context target=main.ts", stderr: "" };
    });

    const result = await client.callTool({ name: "ix_context", arguments: { target: "src/main.ts" } });

    expect(result.isError).toBeFalsy();
    expect(calls).toEqual([["context", "--format=llm", "--", "src/main.ts"]]);
  });

  it("marks Ix command failures as MCP errors", async () => {
    const client = await connect(async () => ({
      ok: false,
      stdout: "",
      stderr: "Session expired",
    }));

    const result = await client.callTool({ name: "ix_stats", arguments: {} });

    expect(result.isError).toBe(true);
    expect(result.content).toEqual([
      {
        type: "text",
        text: JSON.stringify({ error: "Session expired", tool: "ix_stats" }),
      },
    ]);
  });

  it("preserves structured CLI errors written to stdout", async () => {
    const client = await connect(async () => ({
      ok: false,
      stdout: "error code=backend_unreachable message=offline",
      stderr: "",
    }));

    const result = await client.callTool({ name: "ix_health", arguments: {} });

    expect(result.isError).toBe(true);
    expect(result.content).toEqual([{
      type: "text",
      text: "error code=backend_unreachable message=offline",
    }]);
  });

  it("maps the workspace, never a file, even when a caller still sends file", async () => {
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return { ok: true, stdout: "{}", stderr: "" };
    });

    const result = await client.callTool({ name: "ix_map", arguments: { file: "src/service.ts" } });

    expect(result.isError).toBeFalsy();
    expect(calls).toEqual([["map", "--format=json"]]);
  });

  it("applies ix_smells path and limit compatibility without unsupported CLI flags", async () => {
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return {
        ok: true,
        stdout: JSON.stringify({
          count: 3,
          candidates: [
            { file: "ix-cli/src/a.ts", smell: "orphan" },
            { file: "src/nested/b.ts", smell: "orphan" },
            { file: "test/c.ts", smell: "orphan" },
          ],
        }),
        stderr: "",
      };
    });

    const result = await client.callTool({
      name: "ix_smells",
      arguments: { path: "src", limit: 1 },
    });

    expect(calls).toEqual([["smells", "--format=json"]]);
    const content = (result as CallToolResult).content[0];
    expect(content?.type).toBe("text");
    const parsed = JSON.parse(content?.type === "text" ? content.text : "{}");
    expect(parsed.count).toBe(1);
    // Substring, not prefix: `ix-cli/src/a.ts` is what `ix inventory --path src`
    // would have returned, and ix_smells must agree with it.
    expect(parsed.candidates).toEqual([{ file: "ix-cli/src/a.ts", smell: "orphan" }]);
  });

  it("maps ix_ingest onto the github form the plugins used", async () => {
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return { ok: true, stdout: "{}", stderr: "" };
    });

    await client.callTool({
      name: "ix_ingest",
      arguments: { github: "owner/repo", since: "2026-01-01", limit: 25 },
    });

    expect(calls).toEqual([
      ["ingest", "--github=owner/repo", "--since=2026-01-01", "--limit=25", "--format=json"],
    ]);
  });

  it("rejects simultaneous ix_ingest path and github sources before running the CLI", async () => {
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return { ok: true, stdout: "{}", stderr: "" };
    });

    const result = (await client.callTool({
      name: "ix_ingest",
      arguments: { path: "src", github: "owner/repo" },
    })) as CallToolResult;

    expect(calls).toEqual([]);
    expect(result.isError).toBe(true);
    expect(result.structuredContent).toBeUndefined();
    expect(result.content).toEqual([
      {
        type: "text",
        text: JSON.stringify({
          error: "path and github are mutually exclusive; provide only one",
          tool: "ix_ingest",
        }),
      },
    ]);
  });

  it("does not pass --limit when ingesting a local path", async () => {
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return { ok: true, stdout: "{}", stderr: "" };
    });

    await client.callTool({ name: "ix_ingest", arguments: { path: "src" } });

    // --limit is a GitHub paging cap; on a path ingest it is meaningless.
    expect(calls).toEqual([["ingest", "--format=json", "--", "src"]]);
  });

  it("puts positional values behind -- so a leading dash is not read as a flag", async () => {
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return { ok: true, stdout: "{}", stderr: "" };
    });

    await client.callTool({ name: "ix_text", arguments: { pattern: "--path", limit: 20 } });

    // Without the separator commander read `--path` as a flag and swallowed the
    // following `--limit` as its value, so the tool searched for the literal
    // text `20` under a directory named `--limit` and reported ok.
    expect(calls).toEqual([["text", "--limit=20", "--format=llm", "--", "--path"]]);
  });

  it("lists entities by kind without demanding a path, and forwards the limit", async () => {
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return { ok: true, stdout: "{}", stderr: "" };
    });

    // The form CLAUDE.md tells agents to use. A required `path` made it
    // impossible over MCP, and a dropped `--limit` silently capped every answer
    // at the CLI's default 50.
    await client.callTool({ name: "ix_inventory", arguments: { kind: "function", limit: 200 } });

    expect(calls).toEqual([["inventory", "--kind=function", "--limit=200", "--format=llm"]]);
  });

  it("maps ix_decide onto the decide command", async () => {
    const calls: string[][] = [];
    const client = await connect(async (args) => {
      calls.push(args);
      return { ok: true, stdout: "{}", stderr: "" };
    }, true);

    await client.callTool({
      name: "ix_decide",
      arguments: { title: "Use CONTAINS", rationale: "Normalize edges", affects: "Ingestion" },
    });

    expect(calls).toEqual([
      ["decide", "--rationale=Normalize edges", "--affects=Ingestion", "--format=json", "--", "Use CONTAINS"],
    ]);
  });
});