@chainpatrol/mcp 1.10.0

package/dist/index.d.ts

@@ -0,0 +1,279 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export { DEFAULT_API_URL, StoredConfig, configDir, readJsonFile, readStoredConfig, resolveApiUrl } from './chainpatrol-config.js';
+
+/**
+ * The shape of the generated tool manifest.
+ *
+ * The manifest is produced by `scripts/generate-tools.ts`, which walks the
+ * external tRPC router and emits one entry per public API operation. It is
+ * committed to the repo so the published package carries no dependency on the
+ * private router package, and `yarn tools:check` fails CI when the two drift.
+ */
+/** A JSON Schema object, as served to MCP clients in `tools/list`. */
+type JsonSchema = {
+    type?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    [key: string]: unknown;
+};
+type HttpMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+interface ToolDefinition {
+    /** MCP tool name, e.g. `asset_check`. Snake case of the tRPC procedure key. */
+    name: string;
+    /** tRPC procedure key on the external router, e.g. `assetCheck`. */
+    procedure: string;
+    /** REST method and path, used by the HTTP invoker. */
+    method: HttpMethod;
+    path: string;
+    /** Path parameter names extracted from `path`, e.g. `["assetId"]`. */
+    pathParams: string[];
+    /** Short human title, from the procedure's OpenAPI `summary`. */
+    title: string;
+    /** Tool description, from the procedure's OpenAPI `description`. */
+    description: string;
+    tags: string[];
+    /** True for tRPC queries — surfaced to clients as `readOnlyHint`. */
+    readOnly: boolean;
+    /**
+     * True when the API marks the operation deprecated. The tool is still served
+     * — it is a real capability — but the description says so up front so agents
+     * reach for the replacement instead.
+     */
+    deprecated: boolean;
+    /**
+     * True when the procedure's input parser accepts `undefined`.
+     *
+     * MCP has no way to say "this tool takes no arguments" other than an empty
+     * object schema, so `z.void()` and `z.object({})` are indistinguishable in
+     * `inputSchema` — and each rejects what the other accepts. Recorded here at
+     * generation time, where the router is available and `tools:check` makes a
+     * change visible in CI, so the in-process transport does not have to
+     * introspect tRPC internals at runtime to tell them apart.
+     *
+     * Absent rather than `false` when the input is required, to keep the
+     * manifest diff to the procedures this actually applies to.
+     */
+    acceptsNoInput?: true;
+    inputSchema: JsonSchema;
+}
+/**
+ * A large enum lifted out of the tool schemas.
+ *
+ * The asset-type enum alone is 92 values and appears in ten tools; inlining
+ * every copy cost ~17% of the whole `tools/list` payload. Schemas keep a few
+ * example values and point at these, which are served as MCP resources so the
+ * full list stays one fetch away.
+ */
+interface EnumDefinition {
+    name: string;
+    values: string[];
+    /** Tool/property pairs the enum was lifted from, for the resource text. */
+    usedBy: string[];
+}
+/**
+ * Long explanatory prose moved out of an inline schema description.
+ *
+ * Nothing is lost: the text here is the original description verbatim, the
+ * schema keeps its first sentence plus a pointer to `uri`, and the enum of
+ * accepted values stays inline on the property.
+ */
+interface GlossaryDefinition {
+    uri: string;
+    title: string;
+    text: string;
+}
+interface ToolManifest {
+    /** Bumped when the manifest's own shape changes. */
+    manifestVersion: 1;
+    tools: ToolDefinition[];
+    /** Operations deliberately not exposed, with the reason why. */
+    excluded: {
+        path: string;
+        method: string;
+        reason: string;
+    }[];
+    /** Large enums, served as `chainpatrol://enums/<name>` resources. */
+    enums: EnumDefinition[];
+    /** Long descriptions moved into `chainpatrol://glossary/<name>` resources. */
+    glossaries: GlossaryDefinition[];
+}
+
+/**
+ * Dispatches one tool call.
+ *
+ * Everything above this line — the tool list, the schemas, the descriptions,
+ * the prompts and resources — is shared by every deployment. Only dispatch
+ * differs: the remote server holds a tRPC caller and invokes the procedure in
+ * process, while the local server posts to the public REST API. Keeping that
+ * behind one function is what stops the two from drifting apart the way the
+ * SDK drifted from the API.
+ */
+type ToolInvoker = (tool: ToolDefinition, args: Record<string, unknown>) => Promise<unknown>;
+/** Raised for an API response that carries a message worth showing the model. */
+declare class ToolInvocationError extends Error {
+    readonly status: number | undefined;
+    readonly details: unknown;
+    constructor(message: string, options?: {
+        status?: number;
+        details?: unknown;
+        cause?: unknown;
+    });
+}
+
+declare const manifest: ToolManifest;
+interface CreateServerOptions {
+    invoker: ToolInvoker;
+    /**
+     * Restricts the exposed tools by name. Every public API operation is served
+     * by default — this exists only so a caller can trade breadth for context
+     * budget, never to gate capabilities.
+     */
+    only?: string[];
+    serverName?: string;
+    version?: string;
+}
+/**
+ * Above this, a result is cut short rather than handed to the model whole.
+ *
+ * A broad `asset_list` or `detection_list` can otherwise fill a client's
+ * context in a single call, with nothing in the response telling the model it
+ * should have paginated.
+ */
+declare const MAX_RESULT_CHARS = 100000;
+/**
+ * Builds a ChainPatrol MCP server over the generated tool manifest.
+ *
+ * The transport and the dispatch strategy are the caller's choice: pass an
+ * in-process invoker and a streamable-HTTP transport for the remote server, or
+ * an HTTP invoker and a stdio transport for the local one. Both see exactly the
+ * same tools.
+ */
+declare function createChainPatrolMcpServer(options: CreateServerOptions): Server;
+
+/** How the caller authenticates: an org/user API key, or a bearer token. */
+type ApiCredential = {
+    kind: "api-key";
+    value: string;
+} | {
+    kind: "bearer";
+    value: string;
+};
+type CredentialProvider = () => ApiCredential | Promise<ApiCredential>;
+interface HttpInvokerOptions {
+    /** Defaults to `https://app.chainpatrol.io`. */
+    baseUrl?: string;
+    credential: CredentialProvider;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Dispatches tool calls to the public REST API.
+ *
+ * Used by the local (stdio) server, which has no in-process access to the
+ * router. It talks to exactly the endpoints a customer's own script would, with
+ * the credentials the CLI already stores.
+ */
+declare function createHttpInvoker(options: HttpInvokerOptions): ToolInvoker;
+
+interface McpResource {
+    uri: string;
+    name: string;
+    title: string;
+    description: string;
+    mimeType: string;
+    text: string;
+}
+/**
+ * Builds the resource set served alongside the tools.
+ *
+ * Two kinds, both holding content that used to be inlined into every schema:
+ * the large enums (asset types, detection sources) and the glossaries that
+ * explain what a proposal label or reject reason means. Resources are fetched
+ * on demand, so this detail costs nothing until an agent needs it.
+ *
+ * Every resource exists because some tool's schema points at it, so `tools`
+ * narrows the set alongside the tool filter: with the referring tools gone the
+ * resource is unreachable prose, and listing it only spends the context budget
+ * the filter was set to save.
+ */
+declare function buildResources(manifest: ToolManifest, tools?: ToolDefinition[]): McpResource[];
+
+/**
+ * Workflow prompts.
+ *
+ * These carry over the guides that live in the CLI skill file today — the
+ * organization healthcheck and the trend search. There they are always resident
+ * in the model's context; here a client fetches one only when the user is
+ * actually doing that job.
+ *
+ * The procedure is the same, restated in tool vocabulary rather than shell
+ * commands.
+ */
+interface PromptArgument {
+    name: string;
+    description: string;
+    required?: boolean;
+}
+interface PromptDefinition {
+    name: string;
+    title: string;
+    description: string;
+    arguments: PromptArgument[];
+    /**
+     * Every tool the workflow tells the agent to call, by name.
+     *
+     * A prompt is only advertised when all of them are exposed: narrowing the
+     * tool surface with `only` / `CHAINPATROL_MCP_TOOLS` would otherwise leave a
+     * prompt instructing the agent to call tools that are not there.
+     *
+     * `tests/prompts.unit.test.ts` keeps this in step with `template` — every
+     * manifest tool named in the prose has to appear here, and every entry has to
+     * be a real tool.
+     */
+    tools: string[];
+    /** `{{arg}}` placeholders are substituted by `renderPrompt`. */
+    template: string;
+}
+declare const PROMPTS: PromptDefinition[];
+/** Substitutes `{{name}}` placeholders, filling defaults for absent arguments. */
+declare function renderPrompt(prompt: PromptDefinition, args: Record<string, unknown>): string;
+/**
+ * Narrows the prompt set to the workflows every one of whose tools is exposed.
+ *
+ * A prompt is a script for calling tools. Advertising one whose tools have been
+ * filtered out hands the agent instructions it cannot follow, and the failure
+ * surfaces mid-workflow as an unknown-tool error rather than at discovery.
+ */
+declare function selectPrompts(prompts: PromptDefinition[], available: Iterable<string>): PromptDefinition[];
+
+/**
+ * The one knob that narrows the exposed tool surface.
+ *
+ * MCP clients configure servers by command plus environment, not by argv they
+ * can always control, so the variable is the interface that has to work — both
+ * entry points (`chainpatrol-mcp` and `chainpatrol mcp`) read it from here so
+ * there is one parser and one documented name.
+ *
+ * It trades breadth for context budget and is not access control: the API
+ * still authorizes every call against the credential in use.
+ */
+declare const TOOLS_ENV_VAR = "CHAINPATROL_MCP_TOOLS";
+/** The environment shape this reads, so a test can pass one in. */
+type ToolsEnvironment = Record<string, string | undefined>;
+/**
+ * Reads `CHAINPATROL_MCP_TOOLS` as a list of tool names.
+ *
+ * Returns `undefined` — meaning "expose everything" — for an unset, blank, or
+ * all-separator value, so a misconfigured variable widens the surface rather
+ * than silently serving no tools at all.
+ */
+declare function toolsFromEnvironment(env?: ToolsEnvironment): string[] | undefined;
+
+/**
+ * Package version, reported to MCP clients in the initialize handshake.
+ * Kept as a literal so the bundled server needs no filesystem lookup; the
+ * `version.unit.test.ts` check keeps it in step with package.json.
+ */
+declare const PACKAGE_VERSION = "1.10.0";
+
+export { type ApiCredential, type CreateServerOptions, type CredentialProvider, type EnumDefinition, type GlossaryDefinition, type HttpInvokerOptions, type HttpMethod, type JsonSchema, MAX_RESULT_CHARS, type McpResource, PACKAGE_VERSION, PROMPTS, type PromptDefinition, TOOLS_ENV_VAR, type ToolDefinition, ToolInvocationError, type ToolInvoker, type ToolManifest, type ToolsEnvironment, buildResources, createChainPatrolMcpServer, createHttpInvoker, manifest, renderPrompt, selectPrompts, toolsFromEnvironment };

package/dist/index.js

@@ -0,0 +1,41 @@
+import {
+  MAX_RESULT_CHARS,
+  PACKAGE_VERSION,
+  PROMPTS,
+  TOOLS_ENV_VAR,
+  ToolInvocationError,
+  buildResources,
+  createChainPatrolMcpServer,
+  createHttpInvoker,
+  manifest,
+  renderPrompt,
+  selectPrompts,
+  toolsFromEnvironment
+} from "./chunk-AHMNJBKL.js";
+import {
+  DEFAULT_API_URL,
+  configDir,
+  readJsonFile,
+  readStoredConfig,
+  resolveApiUrl
+} from "./chunk-4VHYP4ZH.js";
+export {
+  DEFAULT_API_URL,
+  MAX_RESULT_CHARS,
+  PACKAGE_VERSION,
+  PROMPTS,
+  TOOLS_ENV_VAR,
+  ToolInvocationError,
+  buildResources,
+  configDir,
+  createChainPatrolMcpServer,
+  createHttpInvoker,
+  manifest,
+  readJsonFile,
+  readStoredConfig,
+  renderPrompt,
+  resolveApiUrl,
+  selectPrompts,
+  toolsFromEnvironment
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/stdio-bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/stdio-bin.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import {
+  PACKAGE_VERSION,
+  createChainPatrolMcpServer,
+  createHttpInvoker,
+  toolsFromEnvironment
+} from "./chunk-AHMNJBKL.js";
+import {
+  configDir,
+  readJsonFile,
+  resolveApiUrl
+} from "./chunk-4VHYP4ZH.js";
+
+// src/stdio.ts
+import { DateTime } from "luxon";
+import { join } from "path";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+function resolveCredential() {
+  const envKey = process.env.CHAINPATROL_API_KEY?.trim();
+  if (envKey) return { kind: "api-key", value: envKey };
+  const stored = readJsonFile(
+    join(configDir(), "credentials.json")
+  );
+  if (!stored?.accessToken) {
+    throw new Error(
+      "Not signed in to ChainPatrol. Run `chainpatrol login`, or set CHAINPATROL_API_KEY."
+    );
+  }
+  if (stored.expiresAt) {
+    const expiresAt = DateTime.fromISO(stored.expiresAt, { zone: "utc" });
+    if (expiresAt.isValid && expiresAt < DateTime.now().toUTC()) {
+      throw new Error("ChainPatrol session expired. Run `chainpatrol login` again.");
+    }
+  }
+  return { kind: "bearer", value: stored.accessToken };
+}
+async function main() {
+  const server = createChainPatrolMcpServer({
+    invoker: createHttpInvoker({
+      baseUrl: resolveApiUrl(),
+      credential: resolveCredential
+    }),
+    only: toolsFromEnvironment(),
+    version: PACKAGE_VERSION
+  });
+  await server.connect(new StdioServerTransport());
+}
+
+// src/stdio-bin.ts
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+//# sourceMappingURL=stdio-bin.js.map

package/dist/stdio-bin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stdio.ts","../src/stdio-bin.ts"],"sourcesContent":["/**\n * Local MCP server, spoken over stdio.\n *\n * This module is side-effect free so its resolvers can be tested directly;\n * `stdio-bin.ts` is the executable that calls `main()`.\n *\n * Launched by desktop MCP clients (Claude Code, Claude Desktop, Cursor) and by\n * `chainpatrol mcp`. It dispatches through the public REST API, using the same\n * credentials the CLI stores, so it needs no access to ChainPatrol internals.\n *\n * Credentials, in order:\n *   1. `CHAINPATROL_API_KEY` — for service accounts and CI.\n *   2. The token stored by `chainpatrol login`.\n */\nimport { DateTime } from \"luxon\";\nimport { join } from \"node:path\";\n\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\n\nimport { configDir, readJsonFile, resolveApiUrl } from \"./chainpatrol-config\";\nimport { createHttpInvoker, type ApiCredential } from \"./http-invoker\";\nimport { createChainPatrolMcpServer } from \"./server\";\nimport { toolsFromEnvironment } from \"./tools-filter\";\nimport { PACKAGE_VERSION } from \"./version\";\n\n/**\n * Resolved per call rather than once at startup, so a `chainpatrol login` in\n * another terminal takes effect without restarting the MCP client.\n */\nexport function resolveCredential(): ApiCredential {\n  const envKey = process.env.CHAINPATROL_API_KEY?.trim();\n  if (envKey) return { kind: \"api-key\", value: envKey };\n\n  const stored = readJsonFile<{ accessToken?: string; expiresAt?: string }>(\n    join(configDir(), \"credentials.json\"),\n  );\n\n  if (!stored?.accessToken) {\n    throw new Error(\n      \"Not signed in to ChainPatrol. Run `chainpatrol login`, or set CHAINPATROL_API_KEY.\",\n    );\n  }\n\n  if (stored.expiresAt) {\n    // Luxon in UTC, per AGENTS.md — no `Date.now()` in application code.\n    const expiresAt = DateTime.fromISO(stored.expiresAt, { zone: \"utc\" });\n    if (expiresAt.isValid && expiresAt < DateTime.now().toUTC()) {\n      throw new Error(\"ChainPatrol session expired. Run `chainpatrol login` again.\");\n    }\n  }\n\n  return { kind: \"bearer\", value: stored.accessToken };\n}\n\nexport async function main(): Promise<void> {\n  const server = createChainPatrolMcpServer({\n    invoker: createHttpInvoker({\n      baseUrl: resolveApiUrl(),\n      credential: resolveCredential,\n    }),\n    only: toolsFromEnvironment(),\n    version: PACKAGE_VERSION,\n  });\n\n  await server.connect(new StdioServerTransport());\n}\n","#!/usr/bin/env node\n/**\n * Executable entrypoint for the local MCP server.\n *\n * Kept separate from `stdio.ts` so that module stays importable — and testable\n * — without starting a server as a side effect.\n */\nimport { main } from \"./stdio\";\n\nmain().catch((error: unknown) => {\n  // stdout carries the protocol, so diagnostics have to go to stderr.\n  console.error(error instanceof Error ? error.message : String(error));\n  process.exit(1);\n});\n"],"mappings":";;;;;;;;;;;;;;AAcA,SAAS,gBAAgB;AACzB,SAAS,YAAY;AAErB,SAAS,4BAA4B;AAY9B,SAAS,oBAAmC;AACjD,QAAM,SAAS,QAAQ,IAAI,qBAAqB,KAAK;AACrD,MAAI,OAAQ,QAAO,EAAE,MAAM,WAAW,OAAO,OAAO;AAEpD,QAAM,SAAS;AAAA,IACb,KAAK,UAAU,GAAG,kBAAkB;AAAA,EACtC;AAEA,MAAI,CAAC,QAAQ,aAAa;AACxB,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,MAAI,OAAO,WAAW;AAEpB,UAAM,YAAY,SAAS,QAAQ,OAAO,WAAW,EAAE,MAAM,MAAM,CAAC;AACpE,QAAI,UAAU,WAAW,YAAY,SAAS,IAAI,EAAE,MAAM,GAAG;AAC3D,YAAM,IAAI,MAAM,6DAA6D;AAAA,IAC/E;AAAA,EACF;AAEA,SAAO,EAAE,MAAM,UAAU,OAAO,OAAO,YAAY;AACrD;AAEA,eAAsB,OAAsB;AAC1C,QAAM,SAAS,2BAA2B;AAAA,IACxC,SAAS,kBAAkB;AAAA,MACzB,SAAS,cAAc;AAAA,MACvB,YAAY;AAAA,IACd,CAAC;AAAA,IACD,MAAM,qBAAqB;AAAA,IAC3B,SAAS;AAAA,EACX,CAAC;AAED,QAAM,OAAO,QAAQ,IAAI,qBAAqB,CAAC;AACjD;;;ACxDA,KAAK,EAAE,MAAM,CAAC,UAAmB;AAE/B,UAAQ,MAAM,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;AACpE,UAAQ,KAAK,CAAC;AAChB,CAAC;","names":[]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@chainpatrol/mcp",
+  "description": "The official ChainPatrol MCP server — every public API capability as an MCP tool",
+  "author": "ChainPatrol <support@chainpatrol.io>",
+  "version": "1.10.0",
+  "license": "UNLICENSED",
+  "homepage": "https://chainpatrol.com/docs/mcp",
+  "keywords": [
+    "chainpatrol",
+    "mcp",
+    "model-context-protocol",
+    "agent"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/chainpatrol-config.d.ts",
+      "import": "./dist/chainpatrol-config.js"
+    }
+  },
+  "bin": {
+    "chainpatrol-mcp": "./dist/stdio-bin.js"
+  },
+  "files": [
+    "./dist/**"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "tools:generate": "tsx scripts/generate-tools.ts",
+    "tools:check": "tsx scripts/generate-tools.ts --check",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.unit.ts",
+    "lint:eslint": "eslint . --flag unstable_native_nodejs_ts_config --cache --cache-location .cache/.eslintcache",
+    "lint": "npx oxlint ."
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "luxon": "^3.4.4",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@chainpatrol/eslint-config": "0.0.1",
+    "@chainpatrol/external-trpc": "0.0.0",
+    "@chainpatrol/tsconfig": "0.0.0",
+    "@types/luxon": "^3.4.2",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.39.1",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.4",
+    "typescript": "6.0.2",
+    "vitest": "^3.2.4",
+    "zod-to-json-schema": "^3.24.5"
+  }
+}