@vectros-ai/mcp-server 0.5.0

package/dist/index.d.mts

@@ -0,0 +1,215 @@
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { Logger } from 'pino';
+export { Logger } from 'pino';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+/**
+ * Structured logger — pino, always to stderr.
+ *
+ * CRITICAL: stdout is reserved for the MCP JSON-RPC stream when the
+ * server runs over stdio transport. Anything written to stdout that
+ * is not a valid JSON-RPC message corrupts the protocol and the
+ * client disconnects.
+ *
+ * Every log line goes to stderr. There are no exceptions.
+ */
+
+interface LogContext {
+    debug?: boolean;
+}
+/**
+ * Build a stderr-destined logger.
+ *
+ * Pass `debug: true` (or set `VECTROS_MCP_DEBUG=1`) to lower the
+ * level to `debug`. Default is `info`.
+ */
+declare function createLogger(ctx?: LogContext): Logger;
+
+/**
+ * Shared tool-definition shape.
+ *
+ * Each tool is built as a factory that takes the Vectros SDK client
+ * (already authenticated) + a logger, and returns the registration
+ * payload for `server.registerTool()` plus the handler. The server
+ * class iterates the array and registers each one.
+ */
+
+/**
+ * Names of all REGISTERED tools — the contract for what
+ * `tools: [...]` accepts and what default construction registers.
+ *
+ * MUST stay in lockstep with `ALL_TOOL_FACTORIES` in `./index.ts` —
+ * every name here needs a factory there, and vice versa. The server
+ * iterates this list at construction; an unimplemented name throws.
+ *
+ * v0.1 (shipped 2026-05-30): hybrid_search, record_query, rag_ask, document_ask
+ * v0.2 (shipped):             list_schemas, document_get, current_identity, document_ingest
+ * launch data-plane I/O:      record_get, record_create, record_update, record_delete (tier 1);
+ *                             document_query (tier 2);
+ *                             document_update, document_delete, folder_query,
+ *                             folder_create, folder_update, folder_delete (tier 3)
+ *                             (see the data-plane surface doc)
+ * parity sweep:               lookup_principal (identity resolution for the
+ *                             ownership filters), version_history (record/document
+ *                             audit trail)
+ */
+declare const TOOL_NAMES: readonly ["hybrid_search", "record_query", "record_get", "record_create", "record_update", "record_delete", "rag_ask", "document_ask", "list_schemas", "document_get", "document_query", "document_update", "document_delete", "folder_query", "folder_create", "folder_update", "folder_delete", "current_identity", "document_ingest", "lookup_principal", "version_history"];
+type ToolName = (typeof TOOL_NAMES)[number];
+
+/**
+ * Shared resource-definition shape — mirror of the tool factory
+ * pattern in ../tools/types.ts.
+ *
+ * MCP resources are read-only data discoverable via resources/list +
+ * resources/read JSON-RPC calls. Each resource has a stable URI,
+ * a human-readable name + description, a MIME type, and a `read()`
+ * function that returns its text content.
+ */
+
+/**
+ * Names of all REGISTERED resources — the contract for what
+ * `resources: [...]` filter accepts.
+ *
+ * MUST stay in lockstep with `ALL_RESOURCE_FACTORIES` in
+ * `./index.ts` — every name here needs a factory there, and vice
+ * versa. The server iterates this list at construction; an
+ * unimplemented name throws.
+ */
+declare const RESOURCE_NAMES: readonly ["schemas", "identity"];
+type ResourceName = (typeof RESOURCE_NAMES)[number];
+
+interface VectrosMCPServerOptions {
+    /** Vectros API key. REQUIRED. Recommended shape: ssk_live_... or ssk_test_.... */
+    apiKey: string;
+    /** Opt-in tool filter. Default: all v0.1 tools enabled. */
+    tools?: ToolName[];
+    /**
+     * Opt-in resource filter (v0.2+). Default: all resources enabled.
+     * Pass `[]` to register zero resources (server advertises no
+     * resources capability via tools/list).
+     */
+    resources?: ResourceName[];
+    /**
+     * Vectros API base URL. Default: https://api.vectros.ai. The SDK
+     * calls this `environment`; we keep the docs-aligned name on our
+     * surface to match the design doc.
+     */
+    apiBaseUrl?: string;
+    /** Provide a logger to capture server output. Default: pino → stderr. */
+    logger?: Logger;
+    /**
+     * Which transport this server will be wired up with. Optional; only
+     * affects tool behavior that depends on partner-local-fs access
+     * (currently `document_ingest`'s filePath mode is stdio-only). The
+     * CLI entry points set this — `cli.ts` passes 'stdio', the v0.2
+     * `cli-http.ts` passes 'http'. Programmatic embedders default to
+     * 'stdio' semantics if omitted.
+     */
+    transport?: 'stdio' | 'http';
+    /**
+     * If true (default in v0.2), perform a GET /v1/ping check during
+     * `connect()` to fail-fast on bad credentials BEFORE the MCP
+     * client sends its first tool call. The default is safe — partners
+     * who don't want the network roundtrip on startup can set false,
+     * but the trade-off is "credential failures surface mid-tool-call
+     * rather than at startup."
+     *
+     * The CLI honors `VECTROS_MCP_SKIP_PING_VALIDATION=1` env var as
+     * an explicit opt-out (sets this to false). Useful in CI / dev
+     * environments where the API isn't reachable.
+     */
+    validateOnStart?: boolean;
+    /**
+     * Filesystem root that `document_ingest`'s stdio `filePath` mode is
+     * jailed to. Overrides `VECTROS_MCP_INGEST_ROOT`; when both are
+     * absent the tool defaults to `process.cwd()`.
+     */
+    ingestRoot?: string;
+}
+declare class VectrosMCPServer {
+    private readonly server;
+    private readonly log;
+    private readonly tools;
+    private readonly resources;
+    private readonly apiKey;
+    private readonly environment;
+    private readonly validateOnStart;
+    constructor(opts: VectrosMCPServerOptions);
+    /**
+     * Wire `tools/list` and `tools/call` JSON-RPC handlers on the
+     * underlying MCP Server. Each tool's handler is wrapped to convert
+     * thrown errors into `isError: true` tool results.
+     */
+    private wireHandlers;
+    /**
+     * Connect the underlying MCP Server to a transport (stdio, HTTP,
+     * etc.). Returns when the connection is established; the server
+     * continues serving until the transport closes.
+     *
+     * If `validateOnStart` (default true) is enabled, performs a
+     * GET /v1/ping check BEFORE wiring the transport. On failure,
+     * throws — the partner's MCP client sees a startup error instead
+     * of a confusing "tools work but the first call 401s" experience.
+     */
+    connect(transport: Transport): Promise<void>;
+    /**
+     * GET /v1/ping with the configured credential. Throws on non-2xx.
+     * Called by `connect()` if `validateOnStart` is true.
+     *
+     * Uses `resolveIdentity` so it stays in lockstep with the
+     * graceful-degradation contract (works whether backend has shipped
+     * the extended ping shape or not — we only care about the 2xx vs
+     * non-2xx signal for validation).
+     */
+    private validateCredentials;
+    /** Close the underlying MCP Server. Idempotent. */
+    close(): Promise<void>;
+    /**
+     * Names of the tools registered on this server, in registration
+     * order. Useful for tests + diagnostic logs. Read-only — the
+     * registered set is fixed at construction time.
+     */
+    get registeredToolNames(): readonly ToolName[];
+    /**
+     * Names of the resources registered on this server, in
+     * registration order. Read-only.
+     */
+    get registeredResourceNames(): readonly ResourceName[];
+}
+
+/**
+ * Stdio transport wiring.
+ *
+ * Re-exports the MCP SDK's `StdioServerTransport` so consumers don't
+ * need to know the SDK's internal module path. In v0.2 the HTTP
+ * transport will land alongside as `transport/http.ts`.
+ *
+ * Convention: this module ONLY constructs and returns the transport.
+ * Connecting it to the server is the caller's responsibility (see
+ * `cli.ts` for the standard wiring).
+ */
+
+declare function createStdioTransport(): StdioServerTransport;
+
+/**
+ * API key format validation + credential-type warnings.
+ *
+ * Vectros has three credential types:
+ *   sk_*   — root API key. Wildcard scope. Too broad for desktop MCP;
+ *            warn the user on accept.
+ *   ssk_*  — server-side scoped key. Long-lived, narrowable scope.
+ *            The RECOMMENDED credential for MCP. Accept silently.
+ *   st_*   — short-lived KMS-signed JWT (1h default / 24h max).
+ *            Will expire mid-session; warn the user on accept.
+ *
+ * See the Vectros developer documentation on the auth model and
+ * scoped tokens ("When ssk_* is the right call") for the full rationale.
+ */
+
+type KeyPrefix = 'sk' | 'ssk' | 'st';
+type KeyEnv = 'live' | 'test';
+declare class InvalidApiKeyError extends Error {
+    constructor(reason: string);
+}
+
+export { InvalidApiKeyError, type KeyEnv, type KeyPrefix, RESOURCE_NAMES, type ResourceName, TOOL_NAMES, type ToolName, VectrosMCPServer, type VectrosMCPServerOptions, createLogger, createStdioTransport };

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { Logger } from 'pino';
+export { Logger } from 'pino';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+/**
+ * Structured logger — pino, always to stderr.
+ *
+ * CRITICAL: stdout is reserved for the MCP JSON-RPC stream when the
+ * server runs over stdio transport. Anything written to stdout that
+ * is not a valid JSON-RPC message corrupts the protocol and the
+ * client disconnects.
+ *
+ * Every log line goes to stderr. There are no exceptions.
+ */
+
+interface LogContext {
+    debug?: boolean;
+}
+/**
+ * Build a stderr-destined logger.
+ *
+ * Pass `debug: true` (or set `VECTROS_MCP_DEBUG=1`) to lower the
+ * level to `debug`. Default is `info`.
+ */
+declare function createLogger(ctx?: LogContext): Logger;
+
+/**
+ * Shared tool-definition shape.
+ *
+ * Each tool is built as a factory that takes the Vectros SDK client
+ * (already authenticated) + a logger, and returns the registration
+ * payload for `server.registerTool()` plus the handler. The server
+ * class iterates the array and registers each one.
+ */
+
+/**
+ * Names of all REGISTERED tools — the contract for what
+ * `tools: [...]` accepts and what default construction registers.
+ *
+ * MUST stay in lockstep with `ALL_TOOL_FACTORIES` in `./index.ts` —
+ * every name here needs a factory there, and vice versa. The server
+ * iterates this list at construction; an unimplemented name throws.
+ *
+ * v0.1 (shipped 2026-05-30): hybrid_search, record_query, rag_ask, document_ask
+ * v0.2 (shipped):             list_schemas, document_get, current_identity, document_ingest
+ * launch data-plane I/O:      record_get, record_create, record_update, record_delete (tier 1);
+ *                             document_query (tier 2);
+ *                             document_update, document_delete, folder_query,
+ *                             folder_create, folder_update, folder_delete (tier 3)
+ *                             (see the data-plane surface doc)
+ * parity sweep:               lookup_principal (identity resolution for the
+ *                             ownership filters), version_history (record/document
+ *                             audit trail)
+ */
+declare const TOOL_NAMES: readonly ["hybrid_search", "record_query", "record_get", "record_create", "record_update", "record_delete", "rag_ask", "document_ask", "list_schemas", "document_get", "document_query", "document_update", "document_delete", "folder_query", "folder_create", "folder_update", "folder_delete", "current_identity", "document_ingest", "lookup_principal", "version_history"];
+type ToolName = (typeof TOOL_NAMES)[number];
+
+/**
+ * Shared resource-definition shape — mirror of the tool factory
+ * pattern in ../tools/types.ts.
+ *
+ * MCP resources are read-only data discoverable via resources/list +
+ * resources/read JSON-RPC calls. Each resource has a stable URI,
+ * a human-readable name + description, a MIME type, and a `read()`
+ * function that returns its text content.
+ */
+
+/**
+ * Names of all REGISTERED resources — the contract for what
+ * `resources: [...]` filter accepts.
+ *
+ * MUST stay in lockstep with `ALL_RESOURCE_FACTORIES` in
+ * `./index.ts` — every name here needs a factory there, and vice
+ * versa. The server iterates this list at construction; an
+ * unimplemented name throws.
+ */
+declare const RESOURCE_NAMES: readonly ["schemas", "identity"];
+type ResourceName = (typeof RESOURCE_NAMES)[number];
+
+interface VectrosMCPServerOptions {
+    /** Vectros API key. REQUIRED. Recommended shape: ssk_live_... or ssk_test_.... */
+    apiKey: string;
+    /** Opt-in tool filter. Default: all v0.1 tools enabled. */
+    tools?: ToolName[];
+    /**
+     * Opt-in resource filter (v0.2+). Default: all resources enabled.
+     * Pass `[]` to register zero resources (server advertises no
+     * resources capability via tools/list).
+     */
+    resources?: ResourceName[];
+    /**
+     * Vectros API base URL. Default: https://api.vectros.ai. The SDK
+     * calls this `environment`; we keep the docs-aligned name on our
+     * surface to match the design doc.
+     */
+    apiBaseUrl?: string;
+    /** Provide a logger to capture server output. Default: pino → stderr. */
+    logger?: Logger;
+    /**
+     * Which transport this server will be wired up with. Optional; only
+     * affects tool behavior that depends on partner-local-fs access
+     * (currently `document_ingest`'s filePath mode is stdio-only). The
+     * CLI entry points set this — `cli.ts` passes 'stdio', the v0.2
+     * `cli-http.ts` passes 'http'. Programmatic embedders default to
+     * 'stdio' semantics if omitted.
+     */
+    transport?: 'stdio' | 'http';
+    /**
+     * If true (default in v0.2), perform a GET /v1/ping check during
+     * `connect()` to fail-fast on bad credentials BEFORE the MCP
+     * client sends its first tool call. The default is safe — partners
+     * who don't want the network roundtrip on startup can set false,
+     * but the trade-off is "credential failures surface mid-tool-call
+     * rather than at startup."
+     *
+     * The CLI honors `VECTROS_MCP_SKIP_PING_VALIDATION=1` env var as
+     * an explicit opt-out (sets this to false). Useful in CI / dev
+     * environments where the API isn't reachable.
+     */
+    validateOnStart?: boolean;
+    /**
+     * Filesystem root that `document_ingest`'s stdio `filePath` mode is
+     * jailed to. Overrides `VECTROS_MCP_INGEST_ROOT`; when both are
+     * absent the tool defaults to `process.cwd()`.
+     */
+    ingestRoot?: string;
+}
+declare class VectrosMCPServer {
+    private readonly server;
+    private readonly log;
+    private readonly tools;
+    private readonly resources;
+    private readonly apiKey;
+    private readonly environment;
+    private readonly validateOnStart;
+    constructor(opts: VectrosMCPServerOptions);
+    /**
+     * Wire `tools/list` and `tools/call` JSON-RPC handlers on the
+     * underlying MCP Server. Each tool's handler is wrapped to convert
+     * thrown errors into `isError: true` tool results.
+     */
+    private wireHandlers;
+    /**
+     * Connect the underlying MCP Server to a transport (stdio, HTTP,
+     * etc.). Returns when the connection is established; the server
+     * continues serving until the transport closes.
+     *
+     * If `validateOnStart` (default true) is enabled, performs a
+     * GET /v1/ping check BEFORE wiring the transport. On failure,
+     * throws — the partner's MCP client sees a startup error instead
+     * of a confusing "tools work but the first call 401s" experience.
+     */
+    connect(transport: Transport): Promise<void>;
+    /**
+     * GET /v1/ping with the configured credential. Throws on non-2xx.
+     * Called by `connect()` if `validateOnStart` is true.
+     *
+     * Uses `resolveIdentity` so it stays in lockstep with the
+     * graceful-degradation contract (works whether backend has shipped
+     * the extended ping shape or not — we only care about the 2xx vs
+     * non-2xx signal for validation).
+     */
+    private validateCredentials;
+    /** Close the underlying MCP Server. Idempotent. */
+    close(): Promise<void>;
+    /**
+     * Names of the tools registered on this server, in registration
+     * order. Useful for tests + diagnostic logs. Read-only — the
+     * registered set is fixed at construction time.
+     */
+    get registeredToolNames(): readonly ToolName[];
+    /**
+     * Names of the resources registered on this server, in
+     * registration order. Read-only.
+     */
+    get registeredResourceNames(): readonly ResourceName[];
+}
+
+/**
+ * Stdio transport wiring.
+ *
+ * Re-exports the MCP SDK's `StdioServerTransport` so consumers don't
+ * need to know the SDK's internal module path. In v0.2 the HTTP
+ * transport will land alongside as `transport/http.ts`.
+ *
+ * Convention: this module ONLY constructs and returns the transport.
+ * Connecting it to the server is the caller's responsibility (see
+ * `cli.ts` for the standard wiring).
+ */
+
+declare function createStdioTransport(): StdioServerTransport;
+
+/**
+ * API key format validation + credential-type warnings.
+ *
+ * Vectros has three credential types:
+ *   sk_*   — root API key. Wildcard scope. Too broad for desktop MCP;
+ *            warn the user on accept.
+ *   ssk_*  — server-side scoped key. Long-lived, narrowable scope.
+ *            The RECOMMENDED credential for MCP. Accept silently.
+ *   st_*   — short-lived KMS-signed JWT (1h default / 24h max).
+ *            Will expire mid-session; warn the user on accept.
+ *
+ * See the Vectros developer documentation on the auth model and
+ * scoped tokens ("When ssk_* is the right call") for the full rationale.
+ */
+
+type KeyPrefix = 'sk' | 'ssk' | 'st';
+type KeyEnv = 'live' | 'test';
+declare class InvalidApiKeyError extends Error {
+    constructor(reason: string);
+}
+
+export { InvalidApiKeyError, type KeyEnv, type KeyPrefix, RESOURCE_NAMES, type ResourceName, TOOL_NAMES, type ToolName, VectrosMCPServer, type VectrosMCPServerOptions, createLogger, createStdioTransport };