@jupiterone/jupiterone-mcp/dist/server/tools/types.d.ts

Model Context Protocol server for JupiterOne account rules and rule details

import { z } from 'zod';
import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
import type { JupiterOneClient } from '../../client/jupiterone-client.js';
import type { J1QLValidator } from '../../utils/j1ql-validator.js';
/** A tool result envelope. Structurally compatible with the MCP SDK's CallToolResult. */
export interface ToolResult {
    content: Array<{
        type: 'text';
        text: string;
    }>;
    isError?: boolean;
    /** Typed payload (P1). The SDK validates it against the tool's outputSchema on success. */
    structuredContent?: Record<string, unknown> | unknown[];
}
/** A JupiterOne account the caller can access, surfaced by account-discovery tools. */
export interface AccountSummary {
    accountId: string;
    displayName: string;
}
/**
 * Resolves the accounts the caller can access. Supplied by the host (the remote proxy) because the
 * list comes from a host-only source (a private iam endpoint), not the GraphQL/bearer client.
 */
export type AccountResolver = () => Promise<AccountSummary[]>;
/**
 * Per-call capabilities the chokepoint provides to handlers. Most tools ignore it; the account-discovery
 * tool uses `resolveAccounts`.
 */
export interface ToolContext {
    /** Resolve the caller's accounts. Present only when the host supplies a resolver (multi-tenant remote). */
    resolveAccounts?: AccountResolver;
}
/** Handler for a tool. Receives request-scoped, account-resolved dependencies and call context. */
export type ToolHandler<T extends z.ZodRawShape> = (params: z.infer<z.ZodObject<T>>, client: JupiterOneClient, validator: J1QLValidator, context: ToolContext) => Promise<ToolResult>;
/**
 * Declarative description of a tool. Modules export arrays of these; the server registers
 * them through one chokepoint that applies account scoping, error wrapping, and telemetry.
 */
export interface ToolDefinition<T extends z.ZodRawShape = z.ZodRawShape> {
    name: string;
    /** Human-friendly display title (MCP `title`, required for the connector directory). */
    title: string;
    description: string;
    inputSchema: T;
    /** Output schema (P1). When set, the SDK requires conforming structuredContent on success results. */
    outputSchema?: z.ZodRawShape;
    /**
     * When true, the multi-tenant chokepoint neither injects nor requires an `accountId`, and the tool
     * runs against the unscoped (token-only) client. Used by account-discovery tools like `list-accounts`.
     */
    accountAgnostic?: boolean;
    /**
     * When true, the tool is registered only when the host supplies an account resolver (the
     * multi-tenant remote). `list-accounts` uses this — a fixed-account connector and the stdio client
     * have nothing to list.
     */
    requiresAccountResolver?: boolean;
    /** Behavior hints. `readOnlyHint`/`destructiveHint` are required by the directory review. */
    annotations: ToolAnnotations;
    handler: ToolHandler<T>;
    /** Prefix for the generic error envelope when the handler throws (e.g. "Error listing rules"). */
    errorContext: string;
    /** Optional validator-aware error formatter (J1QL uses this for actionable suggestions). */
    formatError?: (error: unknown, params: z.infer<z.ZodObject<T>>, validator: J1QLValidator) => ToolResult;
}
/**
 * Identity helper that preserves per-tool input-schema inference inside a tool literal while
 * widening the result so heterogeneous tools collect into one `ToolDefinition[]`.
 */
export declare function defineTool<T extends z.ZodRawShape>(def: ToolDefinition<T>): ToolDefinition;
/** Annotation presets. A read tool, a pure create, and a state-mutating call (update/evaluate). */
export declare const READ_ONLY: ToolAnnotations;
export declare const CREATE: ToolAnnotations;
export declare const MUTATE: ToolAnnotations;
//# sourceMappingURL=types.d.ts.map