@finctl/mcp 0.1.0

package/dist/client/finctl-client.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Typed HTTP client for the FinCtl backend (the `dashboard-api` Lambda in the
+ * finctl-core repo). The MCP server is a client of that API: cost tools proxy
+ * to existing analyzer endpoints rather than querying DynamoDB directly.
+ *
+ * Auth: the backend authenticates with a Cognito Bearer token and scopes data
+ * by customer. Until the API-key -> backend-token exchange lands (backend work,
+ * tracked alongside distribution in FIN-1470), the MCP server forwards:
+ *   - Authorization: Bearer <FINCTL_BACKEND_TOKEN>   (service/customer JWT)
+ *   - X-Customer-Id: <customerId>                    (from the authenticated key)
+ * The backend resolves and enforces the customer scope from these.
+ */
+/** A FinCtl backend error surfaced to the caller without a stack trace. */
+export declare class FinCtlApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export interface AccountSpendRow {
+    accountId: string;
+    accountName: string;
+    mtdSpend: number;
+    status: string;
+}
+export interface AccountSpendSummary {
+    periodStart: string;
+    periodEnd: string;
+    total: number;
+    currency: string;
+    accounts: AccountSpendRow[];
+    asOf: string;
+}
+export interface TopCostResource {
+    resourceId: string;
+    name: string;
+    service: string;
+    region: string;
+    accountId: string;
+    cost: number;
+    costSource: "actual" | "savings";
+}
+export interface TopCostResponse {
+    resources: TopCostResource[];
+    total: number;
+}
+export interface Recommendation {
+    resourceId: string;
+    resourceType: string;
+    accountId?: string;
+    estimatedMonthlySavings: number;
+    confidence: "HIGH" | "MEDIUM" | "LOW";
+    actionType: string;
+    reasoning?: string;
+    currentConfiguration?: {
+        instanceType?: string;
+        summary?: string;
+    } | {
+        value?: string;
+    };
+    recommendedConfiguration?: {
+        instanceType?: string;
+        summary?: string;
+    } | {
+        value?: string;
+    };
+}
+export interface RecommendationsResponse {
+    recommendations: Recommendation[];
+}
+export interface Account {
+    accountId: string;
+    accountName?: string;
+}
+export interface AccountsResponse {
+    accounts: Account[];
+}
+export interface SpUtilization {
+    orgWideUtilizationPct: number;
+    totalSPCommitment: number;
+    unusedCommitment: number;
+}
+export interface RiUtilization {
+    orgWideUtilizationPct: number;
+    totalRICost: number;
+    unusedRICost: number;
+}
+export interface ForecastSummary {
+    totalCurrentCost: number;
+    totalForecastCost: number;
+    projectedGrowth: {
+        absolute: number;
+        percentage: number;
+    };
+    confidence: number;
+    period: {
+        start: string;
+        end: string;
+    };
+    budgetStatus?: {
+        budgetAmount?: number;
+        projectedSpend: number;
+        variance: number;
+        warningTriggered: boolean;
+    };
+}
+export interface ForecastResponse {
+    forecast: ForecastSummary | null;
+    isEmpty: boolean;
+    lastUpdated?: string;
+    message?: string;
+}
+export interface Anomaly {
+    anomalyType: string;
+    severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+    service: string;
+    accountId?: string;
+    detectedAt: string;
+    currentValue: number;
+    expectedValue: number;
+    deviation?: number;
+}
+export interface AnomaliesResponse {
+    anomalies: Anomaly[];
+    total: number;
+}
+export interface Budget {
+    id: string;
+    name: string;
+    amount: number;
+    currentSpend: number;
+    forecastedSpend: number;
+    status: "ACTIVE" | "EXCEEDED" | "WARNING" | "INACTIVE";
+    scope?: {
+        type: string;
+        value?: string;
+    };
+    filters?: {
+        accounts?: string[];
+    };
+}
+export interface BudgetsResponse {
+    budgets: Budget[];
+    total: number;
+}
+/** Surface the FinCtl cost API to the tool layer. */
+export interface CostClient {
+    spendSummary(customerId: string): Promise<AccountSpendSummary>;
+    topCost(customerId: string, limit: number): Promise<TopCostResponse>;
+    recommendations(customerId: string, opts: {
+        limit: number;
+        resourceType?: string;
+        accountId?: string;
+    }): Promise<RecommendationsResponse>;
+    accounts(customerId: string): Promise<AccountsResponse>;
+    spUtilization(customerId: string): Promise<SpUtilization>;
+    riUtilization(customerId: string): Promise<RiUtilization>;
+    forecast(customerId: string): Promise<ForecastResponse>;
+    anomalies(customerId: string, opts: {
+        limit: number;
+        timeRange: string;
+    }): Promise<AnomaliesResponse>;
+    budgets(customerId: string): Promise<BudgetsResponse>;
+}
+export interface FinCtlClientOptions {
+    baseUrl: string;
+    /**
+     * Shared MCP service secret (sent as X-Finctl-Mcp-Secret; = backend
+     * MCP_VALIDATE_SECRET). With X-Customer-Id this is how the backend
+     * authenticates and scopes MCP requests (FIN-2648).
+     */
+    serviceSecret?: string;
+    /** Optional Bearer token (Cognito JWT), if a deployment uses one. */
+    token?: string;
+    /** Per-request timeout in ms. */
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare class FinCtlClient implements CostClient {
+    private readonly baseUrl;
+    private readonly serviceSecret?;
+    private readonly token?;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(opts: FinCtlClientOptions);
+    private get;
+    spendSummary(customerId: string): Promise<AccountSpendSummary>;
+    topCost(customerId: string, limit: number): Promise<TopCostResponse>;
+    recommendations(customerId: string, opts: {
+        limit: number;
+        resourceType?: string;
+        accountId?: string;
+    }): Promise<RecommendationsResponse>;
+    accounts(customerId: string): Promise<AccountsResponse>;
+    forecast(customerId: string): Promise<ForecastResponse>;
+    anomalies(customerId: string, opts: {
+        limit: number;
+        timeRange: string;
+    }): Promise<AnomaliesResponse>;
+    budgets(customerId: string): Promise<BudgetsResponse>;
+    spUtilization(customerId: string): Promise<SpUtilization>;
+    riUtilization(customerId: string): Promise<RiUtilization>;
+}
+/**
+ * Build a client from environment configuration.
+ *
+ *   FINCTL_ENDPOINT | FINCTL_DASHBOARD_API_URL   backend base URL (required for live data)
+ *   FINCTL_MCP_SERVICE_SECRET                     shared service secret (= backend MCP_VALIDATE_SECRET)
+ *   FINCTL_BACKEND_TOKEN                          optional Bearer token
+ *
+ * Returns null when no endpoint is configured, so the server can run (handshake,
+ * tool list) without a backend and tools report a clear "not configured" error.
+ */
+export declare function createClientFromEnv(env?: NodeJS.ProcessEnv): FinCtlClient | null;

package/dist/client/finctl-client.js

@@ -0,0 +1,131 @@
+/**
+ * Typed HTTP client for the FinCtl backend (the `dashboard-api` Lambda in the
+ * finctl-core repo). The MCP server is a client of that API: cost tools proxy
+ * to existing analyzer endpoints rather than querying DynamoDB directly.
+ *
+ * Auth: the backend authenticates with a Cognito Bearer token and scopes data
+ * by customer. Until the API-key -> backend-token exchange lands (backend work,
+ * tracked alongside distribution in FIN-1470), the MCP server forwards:
+ *   - Authorization: Bearer <FINCTL_BACKEND_TOKEN>   (service/customer JWT)
+ *   - X-Customer-Id: <customerId>                    (from the authenticated key)
+ * The backend resolves and enforces the customer scope from these.
+ */
+/** A FinCtl backend error surfaced to the caller without a stack trace. */
+export class FinCtlApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "FinCtlApiError";
+    }
+}
+export class FinCtlClient {
+    baseUrl;
+    serviceSecret;
+    token;
+    timeoutMs;
+    fetchImpl;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.serviceSecret = opts.serviceSecret;
+        this.token = opts.token;
+        this.timeoutMs = opts.timeoutMs ?? 15_000;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    async get(path, customerId, query) {
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(query ?? {})) {
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        }
+        const headers = {
+            Accept: "application/json",
+            "X-Customer-Id": customerId,
+        };
+        if (this.serviceSecret)
+            headers["X-Finctl-Mcp-Secret"] = this.serviceSecret;
+        if (this.token)
+            headers.Authorization = `Bearer ${this.token}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(url, { headers, signal: controller.signal });
+        }
+        catch (err) {
+            const reason = err.name === "AbortError" ? "request timed out" : err.message;
+            throw new FinCtlApiError(0, `Could not reach FinCtl API: ${reason}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok) {
+            // Surface the backend's message if present, never a stack trace.
+            let detail = res.statusText;
+            try {
+                const body = (await res.json());
+                detail = body.message ?? body.error ?? detail;
+            }
+            catch {
+                /* non-JSON error body */
+            }
+            throw new FinCtlApiError(res.status, `FinCtl API ${path} failed (${res.status}): ${detail}`);
+        }
+        return (await res.json());
+    }
+    spendSummary(customerId) {
+        return this.get("/api/accounts/spend-summary", customerId);
+    }
+    topCost(customerId, limit) {
+        return this.get("/api/resources/top-cost", customerId, { limit });
+    }
+    recommendations(customerId, opts) {
+        return this.get("/api/recommendations", customerId, {
+            limit: opts.limit,
+            resourceType: opts.resourceType,
+            accountId: opts.accountId,
+        });
+    }
+    accounts(customerId) {
+        return this.get("/api/accounts", customerId);
+    }
+    forecast(customerId) {
+        return this.get("/api/forecast", customerId);
+    }
+    anomalies(customerId, opts) {
+        return this.get("/api/anomalies", customerId, {
+            limit: opts.limit,
+            timeRange: opts.timeRange,
+        });
+    }
+    budgets(customerId) {
+        return this.get("/api/budgets", customerId);
+    }
+    spUtilization(customerId) {
+        return this.get("/api/org/sp-utilization", customerId);
+    }
+    riUtilization(customerId) {
+        return this.get("/api/org/ri-utilization", customerId);
+    }
+}
+/**
+ * Build a client from environment configuration.
+ *
+ *   FINCTL_ENDPOINT | FINCTL_DASHBOARD_API_URL   backend base URL (required for live data)
+ *   FINCTL_MCP_SERVICE_SECRET                     shared service secret (= backend MCP_VALIDATE_SECRET)
+ *   FINCTL_BACKEND_TOKEN                          optional Bearer token
+ *
+ * Returns null when no endpoint is configured, so the server can run (handshake,
+ * tool list) without a backend and tools report a clear "not configured" error.
+ */
+export function createClientFromEnv(env = process.env) {
+    const baseUrl = (env.FINCTL_ENDPOINT || env.FINCTL_DASHBOARD_API_URL)?.trim();
+    if (!baseUrl)
+        return null;
+    return new FinCtlClient({
+        baseUrl,
+        serviceSecret: env.FINCTL_MCP_SERVICE_SECRET?.trim() || undefined,
+        token: env.FINCTL_BACKEND_TOKEN?.trim() || undefined,
+    });
+}
+//# sourceMappingURL=finctl-client.js.map

package/dist/client/finctl-client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { runStdio } from "./transports/stdio.js";
+import { runHttp } from "./transports/http.js";
+import { getVersion } from "./version.js";
+/**
+ * FinCtl MCP server entrypoint.
+ *
+ * Default transport is stdio (for local IDE integrations). Pass --http to run
+ * the hosted Streamable HTTP/SSE transport instead.
+ *
+ *   finctl-mcp                       # stdio
+ *   finctl-mcp --http [--port 8080]  # HTTP/SSE (default port 3000)
+ *   finctl-mcp --endpoint <url>      # point at a FinCtl backend (else FINCTL_ENDPOINT)
+ *   finctl-mcp --version             # print version and exit
+ *   finctl-mcp --help                # print usage and exit
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    // --version / --help short-circuit before any transport or auth, so they work
+    // without FINCTL_API_KEY (e.g. `npx @finctl/mcp --version`).
+    if (args.includes("--version") || args.includes("-v")) {
+        process.stdout.write(`${getVersion()}\n`);
+        return;
+    }
+    if (args.includes("--help") || args.includes("-h")) {
+        printHelp();
+        return;
+    }
+    // --endpoint overrides the backend URL the cost client reads from the env.
+    const endpoint = parseFlag(args, "--endpoint");
+    if (endpoint)
+        process.env.FINCTL_ENDPOINT = endpoint;
+    if (args.includes("--http")) {
+        const port = parsePort(args) ?? (Number(process.env.PORT) || 3000);
+        await runHttp(port);
+    }
+    else {
+        await runStdio();
+    }
+}
+/** Read the value following a `--flag` in argv, if present. */
+function parseFlag(args, flag) {
+    const i = args.indexOf(flag);
+    if (i === -1 || i + 1 >= args.length)
+        return undefined;
+    return args[i + 1];
+}
+function parsePort(args) {
+    const raw = parseFlag(args, "--port");
+    if (raw === undefined)
+        return undefined;
+    const port = Number(raw);
+    return Number.isInteger(port) && port > 0 ? port : undefined;
+}
+function printHelp() {
+    process.stdout.write(`finctl-mcp ${getVersion()} — FinCtl MCP server
+
+Usage:
+  finctl-mcp [options]
+
+Options:
+  --http               Run the HTTP/SSE transport instead of stdio
+  --port <n>           HTTP port (default 3000; or PORT env)
+  --endpoint <url>     FinCtl backend base URL (or FINCTL_ENDPOINT env)
+  -v, --version        Print version and exit
+  -h, --help           Print this help and exit
+
+Environment:
+  FINCTL_API_KEY       Customer API key (required to start the server)
+  FINCTL_ENDPOINT      FinCtl backend base URL
+  FINCTL_BACKEND_TOKEN Bearer token the backend accepts
+
+Docs: https://github.com/finctl/finctl-mcp
+`);
+}
+main().catch((err) => {
+    console.error("[finctl-mcp] fatal:", err);
+    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,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEnC,8EAA8E;IAC9E,6DAA6D;IAC7D,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,UAAU,EAAE,IAAI,CAAC,CAAC;QAC1C,OAAO;IACT,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,SAAS,EAAE,CAAC;QACZ,OAAO;IACT,CAAC;IAED,2EAA2E;IAC3E,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC/C,IAAI,QAAQ;QAAE,OAAO,CAAC,GAAG,CAAC,eAAe,GAAG,QAAQ,CAAC;IAErD,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;QACnE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;SAAM,CAAC;QACN,MAAM,QAAQ,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,SAAS,SAAS,CAAC,IAAc,EAAE,IAAY;IAC7C,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IACvD,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AACrB,CAAC;AAED,SAAS,SAAS,CAAC,IAAc;IAC/B,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACtC,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC;AAED,SAAS,SAAS;IAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,cAAc,UAAU,EAAE;;;;;;;;;;;;;;;;;;CAkB7B,CACE,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;IAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Package identity reported during MCP capability negotiation. */
+export declare const SERVER_INFO: {
+    readonly name: "finctl-mcp";
+    readonly version: string;
+};
+/**
+ * Build a fully-configured FinCtl MCP server with the entire tool catalog
+ * registered. Transport-agnostic — connect the returned server to a stdio or
+ * HTTP/SSE transport (see src/transports/).
+ */
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,35 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { buildTools } from "./tools/catalog.js";
+import { createClientFromEnv } from "./client/finctl-client.js";
+import { getVersion } from "./version.js";
+/** Package identity reported during MCP capability negotiation. */
+export const SERVER_INFO = {
+    name: "finctl-mcp",
+    version: getVersion(),
+};
+/**
+ * Build a fully-configured FinCtl MCP server with the entire tool catalog
+ * registered. Transport-agnostic — connect the returned server to a stdio or
+ * HTTP/SSE transport (see src/transports/).
+ */
+export function createServer() {
+    const server = new McpServer(SERVER_INFO, {
+        capabilities: { tools: {} },
+        instructions: "FinCtl exposes AWS cost intelligence. Use these tools to answer questions about " +
+            "spend, top services, savings recommendations, rightsizing, forecasts, anomalies, " +
+            "and linked accounts. All data is scoped to the authenticated customer's accounts.",
+    });
+    const tools = buildTools({ cost: createClientFromEnv() });
+    for (const tool of tools) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, 
+        // The catalog handler validates/defaults via the same Zod shape the SDK
+        // uses for the wire schema, so the parsed args line up.
+        tool.handler);
+    }
+    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":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,mEAAmE;AACnE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,UAAU,EAAE;CACb,CAAC;AAEX;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,WAAW,EAAE;QACxC,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAC3B,YAAY,EACV,kFAAkF;YAClF,mFAAmF;YACnF,mFAAmF;KACtF,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,UAAU,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,EAAE,CAAC,CAAC;IAC1D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;YACE,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B;QACD,wEAAwE;QACxE,wDAAwD;QACxD,IAAI,CAAC,OAAoD,CAC1D,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tools/catalog.d.ts

@@ -0,0 +1,36 @@
+import { z, type ZodRawShape } from "zod";
+import { type CostClient } from "../client/finctl-client.js";
+/**
+ * The FinCtl MCP tool catalog.
+ *
+ * Each entry defines the tool name, a human-readable title, the description the
+ * customer's AI assistant reads to decide when to call it, and the input schema
+ * (a Zod raw shape — keys map to named tool arguments).
+ *
+ * The four core cost-query tools (get_cost_summary, list_top_services,
+ * get_recommendations, get_savings_plans_coverage) proxy to the FinCtl backend
+ * via {@link CostClient} (FIN-1467). The remaining tools are still stubs; their
+ * data wiring lands in FIN-1468 (account/rightsizing) and FIN-1469
+ * (forecast/anomalies).
+ */
+/** Shape of a single MCP tool result. */
+export interface ToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+}
+/** Dependencies injected into tool handlers. */
+export interface ToolDeps {
+    /** FinCtl backend client, or null when no endpoint is configured. */
+    cost: CostClient | null;
+}
+export interface ToolDefinition<S extends ZodRawShape = ZodRawShape> {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: S;
+    handler: (args: z.objectOutputType<S, z.ZodTypeAny>) => Promise<ToolResult>;
+}
+export declare function buildTools(deps: ToolDeps): ToolDefinition[];