fettle-mcp 0.1.0

package/dist/executor.js

@@ -0,0 +1,202 @@
+/**
+ * Execute a tool call as a real HTTP request against the public API.
+ *
+ * The central decision of S2, held identically in both channels: an MCP tool
+ * call is a transport adapter, not a second implementation of the API. This
+ * module maps a `ToolEntry` plus the model's arguments onto an ordinary
+ * `/v1/...` request carrying the user's key as a Bearer token. Authentication,
+ * the `x-fettle-public-api` scope marker, the per-organization rate bucket,
+ * pydantic validation and pagination all execute in core, unchanged, because
+ * it is a real request hitting the real route.
+ *
+ * Where core's executor dispatches in-process through `httpx.ASGITransport`,
+ * this one goes over the network with `fetch` — but the argument-routing rules
+ * and the success/failure boundary are deliberately the same, so a tool
+ * behaves identically whichever channel a user picked.
+ */
+import { describeFailure, describeTransportFailure } from "./errors.js";
+/**
+ * An argument the model can fix: missing, wrongly typed, or aimed at a
+ * parameter this tool does not declare. Surfaces as an error *tool result*, so
+ * the model reads the explanation and retries.
+ */
+export class ToolArgumentError extends Error {
+}
+/**
+ * A failure the model cannot fix by retrying with different arguments — the
+ * API answered 5xx, or the request never got there. Surfaces as a JSON-RPC
+ * error, the same choice core makes for a 5xx.
+ */
+export class ToolProtocolError extends Error {
+}
+/**
+ * Status codes at or above this boundary are protocol-level failures (the API
+ * itself is broken), not something the calling model can act on.
+ */
+const SERVER_ERROR_THRESHOLD = 500;
+function substitutePathParams(tool, args) {
+    let path = tool.operation.path;
+    for (const name of tool.operation.path_params) {
+        if (!(name in args)) {
+            throw new ToolArgumentError(`Tool '${tool.name}' requires argument '${name}'.`);
+        }
+        const raw = args[name];
+        delete args[name];
+        // A boolean is not a sane identifier even though JavaScript would happily
+        // stringify it — reject it explicitly rather than send "true" as an id.
+        if (typeof raw === "boolean" ||
+            (typeof raw !== "string" && typeof raw !== "number")) {
+            throw new ToolArgumentError(`Tool '${tool.name}' argument '${name}' must be a string or number; ` +
+                `got ${raw === null ? "null" : typeof raw}.`);
+        }
+        const value = String(raw);
+        // An empty value changes which route answers exactly the way a stray '/'
+        // does: DELETE /v1/monitors/ is not the route DELETE
+        // /v1/monitors/{monitor_id}, and the redirect it earns would be reported
+        // as something other than the delete the model asked for.
+        if (value === "") {
+            throw new ToolArgumentError(`Tool '${tool.name}' argument '${name}' must not be empty.`);
+        }
+        // A raw '/' or '?' would add a path segment or open a query string of its
+        // own. Percent-encoding is applied below anyway, but a value containing
+        // either is refused outright rather than quietly retargeted at a
+        // different route — the same rule core's executor enforces.
+        if (value.includes("/") || value.includes("?")) {
+            throw new ToolArgumentError(`Tool '${tool.name}' argument '${name}' may not contain '/' or '?'.`);
+        }
+        path = path.replace(`{${name}}`, encodeURIComponent(value));
+    }
+    return path;
+}
+function buildQuery(tool, args) {
+    const params = new URLSearchParams();
+    for (const name of tool.operation.query) {
+        if (!(name in args)) {
+            continue;
+        }
+        const value = args[name];
+        delete args[name];
+        if (value === undefined || value === null) {
+            continue;
+        }
+        // Arrays become repeated parameters (`regions=eu&regions=us`), which is
+        // how FastAPI reads a list query parameter — a single comma-joined value
+        // would arrive as one malformed member.
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                params.append(name, typeof item === "boolean" ? String(item) : String(item));
+            }
+            continue;
+        }
+        params.append(name, String(value));
+    }
+    return params;
+}
+async function readBody(response) {
+    const text = await response.text();
+    if (text === "") {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Not JSON at all — a proxy's HTML error page, say. Returning the raw text
+        // is more useful to the reader than pretending there was no body.
+        return text;
+    }
+}
+/** Dispatches `tools/call` invocations as requests against the public API. */
+export class ToolExecutor {
+    options;
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    }
+    /**
+     * Execute one tool call and return an MCP `tools/call` result.
+     *
+     * Flow:
+     * 1. Substitute the operation's declared path parameters into the URL
+     *    template, percent-encoding each value so it cannot introduce extra path
+     *    segments or a query string of its own.
+     * 2. Route the declared query parameters into the query string.
+     * 3. Route whatever arguments remain into the JSON body when the operation
+     *    declares one; otherwise an argument that matched no declared parameter
+     *    is rejected rather than silently dropped.
+     * 4. Dispatch the request with the user's key as a Bearer token, following
+     *    no redirects: a 3xx is reported, never chased, so the credential cannot
+     *    be replayed to a host the contract did not name.
+     * 5. Map the response — 2xx is a result, any other non-5xx is an actionable
+     *    tool error, 5xx and transport failures raise.
+     *
+     * Throws:
+     *   ToolArgumentError: an argument is missing, wrongly typed, or matched no
+     *   declared parameter on a tool with no request body.
+     *   ToolProtocolError: the API answered 5xx, or the request never completed.
+     */
+    async execute(tool, args) {
+        const remaining = { ...args };
+        const path = substitutePathParams(tool, remaining);
+        const query = buildQuery(tool, remaining);
+        let body;
+        if (tool.operation.body) {
+            body = JSON.stringify(remaining);
+        }
+        else if (Object.keys(remaining).length > 0) {
+            const unexpected = Object.keys(remaining).sort().join(", ");
+            throw new ToolArgumentError(`Tool '${tool.name}' does not accept argument(s): ${unexpected}.`);
+        }
+        const url = `${this.options.apiUrl}${path}${query.size > 0 ? `?${query}` : ""}`;
+        const headers = {
+            Authorization: `Bearer ${this.options.apiKey}`,
+            Accept: "application/json",
+            "User-Agent": this.options.userAgent,
+        };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method: tool.operation.method,
+                headers,
+                ...(body === undefined ? {} : { body }),
+                redirect: "manual",
+                signal: AbortSignal.timeout(this.options.timeoutMs),
+            });
+        }
+        catch (cause) {
+            if (cause instanceof Error && cause.name === "TimeoutError") {
+                throw new ToolProtocolError(`Tool '${tool.name}' timed out after ${this.options.timeoutMs}ms ` +
+                    `waiting for ${this.options.apiUrl}. Retry, or raise ` +
+                    "FETTLE_TIMEOUT_MS if this endpoint is legitimately slow.");
+            }
+            throw new ToolProtocolError(describeTransportFailure(this.options.apiUrl, cause));
+        }
+        if (response.status >= SERVER_ERROR_THRESHOLD) {
+            throw new ToolProtocolError(`Tool '${tool.name}' failed: the API returned ${response.status}.`);
+        }
+        const payload = await readBody(response);
+        if (response.status < 200 || response.status >= 300) {
+            const errorBody = typeof payload === "object" && payload !== null && !Array.isArray(payload)
+                ? payload
+                : null;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: describeFailure(response.status, errorBody, response.headers),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const text = payload === undefined
+            ? `${tool.name} succeeded (${response.status}); the response had no body.`
+            : JSON.stringify(payload);
+        return { content: [{ type: "text", text }], isError: false };
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * `npx fettle-mcp` — the stdio MCP server for Fettle.
+ *
+ * Everything that can be wrong with the setup is checked here, before the
+ * transport is connected: a missing key, an unusable API URL, a contract this
+ * version cannot read. The reason is the medium — an MCP client spawns this
+ * process with stdout reserved for JSON-RPC frames and nothing but stderr for
+ * a human to read. A configuration mistake discovered later, inside a tool
+ * call, reaches the user as "the assistant could not check your monitor",
+ * which is the wrong diagnosis of the wrong problem.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * `npx fettle-mcp` — the stdio MCP server for Fettle.
+ *
+ * Everything that can be wrong with the setup is checked here, before the
+ * transport is connected: a missing key, an unusable API URL, a contract this
+ * version cannot read. The reason is the medium — an MCP client spawns this
+ * process with stdout reserved for JSON-RPC frames and nothing but stderr for
+ * a human to read. A configuration mistake discovered later, inside a tool
+ * call, reaches the user as "the assistant could not check your monitor",
+ * which is the wrong diagnosis of the wrong problem.
+ */
+import { readFileSync } from "node:fs";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ConfigError, loadConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { ToolExecutor } from "./executor.js";
+import { createServer } from "./server.js";
+const SERVER_NAME = "fettle-mcp";
+/**
+ * The published version, read from the package manifest at startup.
+ *
+ * Reported to the MCP client in `serverInfo` and sent as the `User-Agent` on
+ * every API call, so a support question about odd behaviour can be answered
+ * with "which version" from the server's own logs. `src/` and `dist/` both sit
+ * one level under the package root, so this path is right compiled and under
+ * test alike.
+ */
+function readVersion() {
+    try {
+        const manifestUrl = new URL("../package.json", import.meta.url);
+        const manifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
+        return manifest.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+async function main() {
+    const config = loadConfig();
+    const contract = loadContract();
+    const version = readVersion();
+    const executor = new ToolExecutor({
+        apiUrl: config.apiUrl,
+        apiKey: config.apiKey,
+        timeoutMs: config.timeoutMs,
+        userAgent: `${SERVER_NAME}/${version} (+https://fettle.sh)`,
+    });
+    const server = createServer(contract, executor, {
+        name: SERVER_NAME,
+        version,
+    });
+    await server.connect(new StdioServerTransport());
+    // Nothing is logged on success: stdout carries the protocol, and a startup
+    // banner on stderr shows up in some clients as an error the user must chase.
+}
+main().catch((error) => {
+    const message = error instanceof ConfigError || error instanceof Error
+        ? error.message
+        : String(error);
+    process.stderr.write(`fettle-mcp: ${message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,GAAG,YAAY,CAAC;AAEjC;;;;;;;;GAQG;AACH,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAE5D,CAAC;QACF,OAAO,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;IAE9B,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC;QAChC,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS,EAAE,GAAG,WAAW,IAAI,OAAO,uBAAuB;KAC5D,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE;QAC9C,IAAI,EAAE,WAAW;QACjB,OAAO;KACR,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACjD,2EAA2E;IAC3E,6EAA6E;AAC/E,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GACX,KAAK,YAAY,WAAW,IAAI,KAAK,YAAY,KAAK;QACpD,CAAC,CAAC,KAAK,CAAC,OAAO;QACf,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,OAAO,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Wire the contract, the validators and the executor into an MCP server.
+ *
+ * The server registers no tool by hand. `tools/list` is the contract rendered
+ * into MCP's wire shape, and `tools/call` is "find the entry, validate against
+ * its schema, execute it" — so a tool added in core and re-vendored here
+ * appears in the package without a line of source changing. That is the whole
+ * point of generating the contract in the first place.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type ToolContract } from "./contract.js";
+import { type ToolExecutor } from "./executor.js";
+export interface ServerIdentity {
+    name: string;
+    version: string;
+}
+/**
+ * Build the MCP server.
+ *
+ * The failure surface is split deliberately, matching core's remote channel:
+ * anything the model can fix by calling again with different arguments comes
+ * back as an error *result* it can read and act on, while anything it cannot
+ * — an unknown tool name, a 5xx, an unreachable API — is raised as a protocol
+ * error. Dressing a broken backend up as "here is what to fix" would send the
+ * model into a retry loop against a problem no argument can solve.
+ */
+export declare function createServer(contract: ToolContract, executor: ToolExecutor, identity: ServerIdentity): Server;

package/dist/server.js

@@ -0,0 +1,77 @@
+/**
+ * Wire the contract, the validators and the executor into an MCP server.
+ *
+ * The server registers no tool by hand. `tools/list` is the contract rendered
+ * into MCP's wire shape, and `tools/call` is "find the entry, validate against
+ * its schema, execute it" — so a tool added in core and re-vendored here
+ * appears in the package without a line of source changing. That is the whole
+ * point of generating the contract in the first place.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { findTool } from "./contract.js";
+import { ToolArgumentError, ToolProtocolError } from "./executor.js";
+import { compileValidators, describeSchemaErrors } from "./validation.js";
+/**
+ * Render the contract as MCP tool descriptors.
+ *
+ * `inputSchema` is the wire-format camelCase key; the contract stores the same
+ * data under the snake_case `input_schema` it was generated with. The schema
+ * is passed through untouched — this package must not develop a second opinion
+ * about what a tool's arguments look like.
+ */
+function toWireTools(contract) {
+    return contract.tools.map((tool) => ({
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.input_schema,
+    }));
+}
+/**
+ * Build the MCP server.
+ *
+ * The failure surface is split deliberately, matching core's remote channel:
+ * anything the model can fix by calling again with different arguments comes
+ * back as an error *result* it can read and act on, while anything it cannot
+ * — an unknown tool name, a 5xx, an unreachable API — is raised as a protocol
+ * error. Dressing a broken backend up as "here is what to fix" would send the
+ * model into a retry loop against a problem no argument can solve.
+ */
+export function createServer(contract, executor, identity) {
+    const validators = compileValidators(contract);
+    const wireTools = toWireTools(contract);
+    const server = new Server(identity, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: wireTools }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: rawArguments } = request.params;
+        const tool = findTool(contract, name);
+        if (tool === undefined) {
+            throw new McpError(ErrorCode.InvalidParams, `Unknown tool '${name}'.`);
+        }
+        const args = (rawArguments ?? {});
+        const validate = validators.get(name);
+        if (validate !== undefined && !validate(args)) {
+            return {
+                content: [
+                    { type: "text", text: describeSchemaErrors(name, validate.errors) },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            return await executor.execute(tool, args);
+        }
+        catch (error) {
+            if (error instanceof ToolArgumentError) {
+                return { content: [{ type: "text", text: error.message }], isError: true };
+            }
+            if (error instanceof ToolProtocolError) {
+                throw new McpError(ErrorCode.InternalError, error.message);
+            }
+            throw error;
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/validation.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Argument validation against the contract's own JSON Schemas.
+ *
+ * The schemas are generated from core's pydantic models, so validating here
+ * catches exactly what the API would have rejected — one round trip earlier,
+ * without spending a unit of the organization's rate budget, and with the
+ * offending field named in the same wording a 422 would have used. This is a
+ * pre-filter, never an authority: the API still validates everything, and a
+ * schema that lets something through is core's problem to answer.
+ *
+ * Ajv runs with `strict: false` on purpose. Strict mode rejects schemas over
+ * details of *how* they are written — an unrecognised keyword, a format it
+ * does not know — and this package does not author these schemas, it receives
+ * them. A newly generated contract must never fail to load here because the
+ * generator started emitting a keyword this version had not seen.
+ */
+import { type ErrorObject, type ValidateFunction } from "ajv";
+import type { ToolContract } from "./contract.js";
+export type ToolValidators = Map<string, ValidateFunction>;
+/** Compile one validator per tool, once, at startup. */
+export declare function compileValidators(contract: ToolContract): ToolValidators;
+/**
+ * Turn Ajv's errors into the same field-naming sentence a 422 would produce.
+ *
+ * Deduplicated because `allErrors` reports one entry per failing keyword, and
+ * a single bad value routinely trips two of them — the model does not need to
+ * be told twice about one argument.
+ */
+export declare function describeSchemaErrors(toolName: string, errors: ErrorObject[] | null | undefined): string;

package/dist/validation.js

@@ -0,0 +1,65 @@
+/**
+ * Argument validation against the contract's own JSON Schemas.
+ *
+ * The schemas are generated from core's pydantic models, so validating here
+ * catches exactly what the API would have rejected — one round trip earlier,
+ * without spending a unit of the organization's rate budget, and with the
+ * offending field named in the same wording a 422 would have used. This is a
+ * pre-filter, never an authority: the API still validates everything, and a
+ * schema that lets something through is core's problem to answer.
+ *
+ * Ajv runs with `strict: false` on purpose. Strict mode rejects schemas over
+ * details of *how* they are written — an unrecognised keyword, a format it
+ * does not know — and this package does not author these schemas, it receives
+ * them. A newly generated contract must never fail to load here because the
+ * generator started emitting a keyword this version had not seen.
+ */
+import { Ajv } from "ajv";
+import ajvFormats from "ajv-formats";
+/**
+ * `ajv-formats` is CommonJS whose `module.exports` *is* the plugin function.
+ * Node's ESM interop hands that function straight to a default import, but
+ * TypeScript under NodeNext types the same import as the module namespace, so
+ * the shape is asserted once here rather than fought at the call site.
+ */
+const addFormats = ajvFormats;
+/** Compile one validator per tool, once, at startup. */
+export function compileValidators(contract) {
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajv);
+    const validators = new Map();
+    for (const tool of contract.tools) {
+        validators.set(tool.name, ajv.compile(tool.input_schema));
+    }
+    return validators;
+}
+function describeError(error) {
+    const path = error.instancePath.replace(/^\//, "").replace(/\//g, ".");
+    if (error.keyword === "required") {
+        const missing = error.params.missingProperty;
+        const field = path === "" ? missing : `${path}.${missing}`;
+        return `'${field}': required argument is missing`;
+    }
+    if (error.keyword === "additionalProperties") {
+        const extra = error.params.additionalProperty;
+        const field = path === "" ? extra : `${path}.${extra}`;
+        return `'${field}': unexpected argument — this tool does not accept it`;
+    }
+    const field = path === "" ? "arguments" : path;
+    return `'${field}': ${error.message ?? "is invalid"}`;
+}
+/**
+ * Turn Ajv's errors into the same field-naming sentence a 422 would produce.
+ *
+ * Deduplicated because `allErrors` reports one entry per failing keyword, and
+ * a single bad value routinely trips two of them — the model does not need to
+ * be told twice about one argument.
+ */
+export function describeSchemaErrors(toolName, errors) {
+    const parts = [...new Set((errors ?? []).map(describeError))];
+    if (parts.length === 0) {
+        return `Tool '${toolName}' rejected the arguments. Check them and retry.`;
+    }
+    return `Invalid argument(s) for '${toolName}' — ${parts.join("; ")}. Fix the value(s) and retry.`;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,GAAG,EAA2C,MAAM,KAAK,CAAC;AACnE,OAAO,UAAU,MAAM,aAAa,CAAC;AAMrC;;;;;GAKG;AACH,MAAM,UAAU,GAAG,UAA0C,CAAC;AAE9D,wDAAwD;AACxD,MAAM,UAAU,iBAAiB,CAAC,QAAsB;IACtD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,UAAU,CAAC,GAAG,CAAC,CAAC;IAChB,MAAM,UAAU,GAAmB,IAAI,GAAG,EAAE,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QAClC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,aAAa,CAAC,KAAkB;IACvC,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACvE,IAAI,KAAK,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,OAAO,GAAI,KAAK,CAAC,MAAuC,CAAC,eAAe,CAAC;QAC/E,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3D,OAAO,IAAI,KAAK,iCAAiC,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,KAAK,sBAAsB,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAI,KAAK,CAAC,MAA0C,CAAC,kBAAkB,CAAC;QACnF,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,KAAK,EAAE,CAAC;QACvD,OAAO,IAAI,KAAK,uDAAuD,CAAC;IAC1E,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/C,OAAO,IAAI,KAAK,MAAM,KAAK,CAAC,OAAO,IAAI,YAAY,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgB,EAChB,MAAwC;IAExC,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,SAAS,QAAQ,iDAAiD,CAAC;IAC5E,CAAC;IACD,OAAO,4BAA4B,QAAQ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,+BAA+B,CAAC;AACpG,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "fettle-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Fettle (fettle.sh) uptime monitoring — manage monitors, incidents, heartbeats and status pages from any MCP client.",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "fettle",
+    "uptime",
+    "monitoring",
+    "claude",
+    "cursor"
+  ],
+  "homepage": "https://fettle.sh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/darkweid/monitoring-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/darkweid/monitoring-mcp/issues"
+  },
+  "license": "MIT",
+  "author": "Mark Shamanskii",
+  "type": "module",
+  "bin": {
+    "fettle-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "contracts/mcp_tools.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "packageManager": "pnpm@10.15.1",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "contract:check": "node scripts/check-contract-drift.mjs",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  }
+}