@pungoyal/kite-cli 0.3.0 → 0.5.0

package/dist/commands/doctor.js

@@ -0,0 +1,190 @@
+import { stat } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { getSecret, keyringAvailable } from '../core/credentials.js';
+import { ExitCode } from '../core/errors.js';
+import { configFile } from '../core/paths.js';
+import { isExpired, timeUntilExpiry } from '../core/session.js';
+import { renderKeyValue } from '../output/table.js';
+export const doctorCommands = (program, run) => {
+    program
+        .command('doctor')
+        .description('Run offline health checks on your configuration, credentials, and session')
+        .action(run(doctor));
+};
+async function doctor(ctx) {
+    const checks = [
+        checkNode(),
+        await checkConfigFile(),
+        await checkKeyring(),
+        await checkCredentials(ctx),
+        checkSession(ctx),
+        await checkCallbackPort(ctx),
+    ];
+    const worst = checks.some((c) => c.status === 'fail')
+        ? 'fail'
+        : checks.some((c) => c.status === 'warn')
+            ? 'warn'
+            : 'ok';
+    if (ctx.io.json) {
+        ctx.io.writeJson({
+            ok: worst !== 'fail',
+            profile: ctx.profile.name,
+            env: ctx.env,
+            checks: checks.map((c) => ({
+                name: c.name,
+                status: c.status,
+                detail: c.detail,
+                ...(c.hint ? { hint: c.hint } : {}),
+            })),
+        });
+        if (worst === 'fail')
+            process.exitCode = ExitCode.Failure;
+        return;
+    }
+    const { io } = ctx;
+    const rows = [];
+    for (const check of checks) {
+        rows.push([`${icon(io, check.status)} ${check.name}`, check.detail]);
+        if (check.hint)
+            rows.push(['', io.dim(check.hint)]);
+    }
+    io.line(renderKeyValue(io, rows));
+    io.note('');
+    if (worst === 'fail') {
+        io.error('Some checks failed. See the hints above.');
+        process.exitCode = ExitCode.Failure;
+    }
+    else if (worst === 'warn') {
+        io.warn('All essential checks passed, with warnings.');
+        io.info('Run `kite whoami` to confirm the session is live on Kite (doctor is offline).');
+    }
+    else {
+        io.success('Everything looks healthy.');
+        io.info('Run `kite whoami` to confirm the session against Kite (doctor is offline).');
+    }
+}
+// --- individual checks -----------------------------------------------------
+/** Node must meet the floor declared in package.json `engines`. */
+function checkNode() {
+    const current = process.versions.node;
+    const floor = '22.12.0';
+    return meetsFloor(current, floor)
+        ? { name: 'Node runtime', status: 'ok', detail: `v${current}` }
+        : {
+            name: 'Node runtime',
+            status: 'fail',
+            detail: `v${current} is below the required v${floor}`,
+            hint: `Upgrade to Node ${floor} or newer.`,
+        };
+}
+async function checkConfigFile() {
+    const path = configFile();
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            // No file is fine — defaults apply until the first `config set`.
+            return { name: 'Config file', status: 'ok', detail: 'none yet (using built-in defaults)' };
+        }
+        return { name: 'Config file', status: 'fail', detail: `cannot read ${path}`, hint: err.message };
+    }
+    // Windows models permissions through ACLs, not the POSIX mode bits, so the
+    // 0600 assertion only makes sense off Windows.
+    if (process.platform !== 'win32' && (info.mode & 0o077) !== 0) {
+        const mode = (info.mode & 0o777).toString(8).padStart(3, '0');
+        return {
+            name: 'Config file',
+            status: 'warn',
+            detail: `${path} is mode ${mode} (world- or group-readable)`,
+            hint: `Tighten it: chmod 600 ${path}`,
+        };
+    }
+    return { name: 'Config file', status: 'ok', detail: path };
+}
+async function checkKeyring() {
+    return (await keyringAvailable())
+        ? { name: 'Credential store', status: 'ok', detail: 'OS keyring available' }
+        : {
+            name: 'Credential store',
+            status: 'warn',
+            detail: 'no OS keyring — falling back to an encrypted file',
+            hint: 'Set KITE_CREDENTIALS_PASSPHRASE to enable the encrypted file store on this machine.',
+        };
+}
+async function checkCredentials(ctx) {
+    if (ctx.env === 'sandbox') {
+        return { name: 'API secret', status: 'ok', detail: 'using the public sandbox credentials' };
+    }
+    const secret = await getSecret('api_secret', { scope: ctx.credentialScope });
+    return secret
+        ? { name: 'API secret', status: 'ok', detail: `stored (${secret.backend})` }
+        : {
+            name: 'API secret',
+            status: 'warn',
+            detail: 'not stored',
+            hint: 'Run `kite login` (or set KITE_API_SECRET) so re-login and signing work.',
+        };
+}
+/** Cached session metadata only — liveness against Kite is `kite whoami`'s job. */
+function checkSession(ctx) {
+    const loginHint = ctx.profile.name === 'default' ? 'Run `kite login`.' : `Run \`kite --profile ${ctx.profile.name} login\`.`;
+    if (!ctx.session) {
+        return { name: 'Session', status: 'warn', detail: 'not logged in', hint: loginHint };
+    }
+    if (isExpired(ctx.session)) {
+        return {
+            name: 'Session',
+            status: 'warn',
+            detail: 'expired (Kite invalidates tokens at 06:00 IST daily)',
+            hint: loginHint,
+        };
+    }
+    const who = ctx.session.userName ?? ctx.session.userId;
+    return { name: 'Session', status: 'ok', detail: `${who}, expires in ${timeUntilExpiry(ctx.session)}` };
+}
+async function checkCallbackPort(ctx) {
+    const port = ctx.config.redirectPort;
+    const free = await portIsFree(port);
+    return free
+        ? { name: 'Login callback port', status: 'ok', detail: `127.0.0.1:${port} is free` }
+        : {
+            name: 'Login callback port',
+            status: 'warn',
+            detail: `127.0.0.1:${port} is in use`,
+            hint: 'Another process holds the callback port; `kite login` may fail until it frees, or change redirectPort.',
+        };
+}
+// --- helpers ---------------------------------------------------------------
+function icon(io, status) {
+    switch (status) {
+        case 'ok':
+            return io.green('✓');
+        case 'warn':
+            return io.yellow('!');
+        case 'fail':
+            return io.red('✗');
+    }
+}
+/** True when `current` is >= `floor`, comparing major.minor.patch numerically. */
+export function meetsFloor(current, floor) {
+    const c = current.split('.').map((n) => Number.parseInt(n, 10));
+    const f = floor.split('.').map((n) => Number.parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        const a = c[i] ?? 0;
+        const b = f[i] ?? 0;
+        if (a !== b)
+            return a > b;
+    }
+    return true;
+}
+/** Bind-and-release probe: can `kite login` open its loopback callback server? */
+function portIsFree(port, host = '127.0.0.1') {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => server.close(() => resolve(true)));
+        server.listen(port, host);
+    });
+}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { CommandFactory } from './types.js';
+export declare const mcpCommands: CommandFactory;

package/dist/commands/mcp.js

@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { McpServer } from '../core/mcp.js';
+/**
+ * `kite mcp` — a read-only Model Context Protocol server over stdio.
+ *
+ * Launched by an MCP client (Claude and others) as a subprocess, it lets an
+ * agent inspect a Kite account — holdings, positions, funds, live quotes, the
+ * orderbook, instrument search — but never place, modify or cancel an order.
+ * The rationale for read-only lives in src/core/mcp.ts.
+ *
+ * The stdio contract is strict: the JSON-RPC protocol owns stdout, so every
+ * human-facing message here goes to stderr (io.info/note already do).
+ */
+// Single source of truth for the version, like run.ts. package.json sits two
+// levels up from both src/commands/ (dev) and dist/commands/ (published).
+const VERSION = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+/** Instruments accepted by quote-style tools, e.g. ["NSE:INFY", "NSE:TCS"]. */
+const instrumentsArg = z.object({
+    instruments: z.array(z.string().min(1)).min(1).describe('Instruments as EXCHANGE:TRADINGSYMBOL, e.g. NSE:INFY'),
+});
+const searchArg = z.object({
+    query: z.string().min(1).describe('Free-text query over trading symbol and name'),
+    exchange: z.string().optional().describe('Restrict to an exchange, e.g. NSE, NFO'),
+    type: z.string().optional().describe('Restrict to an instrument type, e.g. EQ, CE, PE, FUT'),
+    limit: z.number().int().positive().max(100).optional().describe('Maximum results (default 25)'),
+});
+/** Build one tool, deriving its advertised JSON Schema from the zod schema. */
+function tool(name, description, schema, handler) {
+    return {
+        name,
+        description,
+        schema,
+        inputSchema: z.toJSONSchema(schema),
+        handler,
+    };
+}
+/** The read-only Kite surface exposed to an agent. */
+function buildTools(ctx) {
+    const { api, instruments, signal } = ctx;
+    const noArgs = z.object({});
+    return [
+        tool('get_profile', 'The authenticated Kite user profile.', noArgs, () => api.getProfile(signal)),
+        tool('get_holdings', 'Long-term holdings with average price and P&L.', noArgs, () => api.getHoldings(signal)),
+        tool('get_positions', 'Open positions (intraday and overnight).', noArgs, () => api.getPositions(signal)),
+        tool('get_funds', 'Available margins and cash balance.', noArgs, () => api.getMargins(signal)),
+        tool('get_orders', "Today's orderbook, including status and fills.", noArgs, () => api.getOrders(signal)),
+        tool('get_trades', "Today's executed trades.", noArgs, () => api.getTrades(signal)),
+        tool('quote', 'Full market quotes for one or more instruments.', instrumentsArg, (a) => api.getQuote(a.instruments, signal)),
+        tool('ltp', 'Last traded price for one or more instruments.', instrumentsArg, (a) => api.getLtp(a.instruments, signal)),
+        tool('ohlc', 'Open/high/low/close plus last price for one or more instruments.', instrumentsArg, (a) => api.getOhlc(a.instruments, signal)),
+        tool('search_instruments', 'Find tradeable instruments by symbol or name.', searchArg, async (a) => {
+            await instruments.load({ signal });
+            return instruments.search(a.query, {
+                exchange: a.exchange,
+                type: a.type,
+                ...(a.limit !== undefined ? { limit: a.limit } : {}),
+            });
+        }),
+    ];
+}
+async function mcp(ctx) {
+    // A live session is required — every tool hits the API. Fail here (exit 3)
+    // rather than starting a server whose every call would 403.
+    ctx.requireSession();
+    const server = new McpServer({
+        name: 'kite-cli',
+        version: VERSION,
+        tools: buildTools(ctx),
+        signal: ctx.signal,
+    });
+    ctx.io.info('kite MCP server ready on stdio (read-only). Launch this from an MCP client; Ctrl-C to stop.');
+    if (ctx.env === 'sandbox')
+        ctx.io.info('Running against the sandbox — no real account.');
+    // stdio is the transport: the process's own stdin/stdout carry JSON-RPC.
+    await server.serve(process.stdin, process.stdout);
+}
+export const mcpCommands = (program, run) => {
+    program
+        .command('mcp')
+        .description('Run a read-only MCP server over stdio for LLM agents (Claude and others)')
+        .action(run(mcp));
+};

package/dist/commands/orders.js

@@ -5,7 +5,7 @@ import { formatInstrumentKey, parseInstrumentKey } from '../core/instruments.js'
 import { TERMINAL_ORDER_STATUSES } from '../core/schemas.js';
 import { dateTime, money, quantity, rupees, timeOnly } from '../output/format.js';
 import { heading, printTable, renderKeyValue, renderTable } from '../output/table.js';
-import { assertTradingEnabled, buildOrderTag, confirmAction } from '../safety.js';
+import { assertTradingEnabled, buildOrderTag, CLI_TAG_PREFIX, confirmAction } from '../safety.js';
 export const orderCommands = (program, run) => {
     const orders = program.command('orders').description('View and manage orders');
     orders
@@ -18,6 +18,11 @@ export const orderCommands = (program, run) => {
         .description('Show the full state history of one order')
         .argument('<order-id>')
         .action(run(getOrder));
+    orders
+        .command('reconcile')
+        .description('Check whether a tagged order reached Kite (recovery after an ambiguous failure)')
+        .argument('[tag]', 'Order tag to look up; omit to list the orders this CLI placed today')
+        .action(run(reconcileOrders));
     orders
         .command('place')
         .description('Place an order')
@@ -473,6 +478,75 @@ async function reconcileAfterFailure(ctx, tag, cause) {
         process.exitCode = ExitCode.Upstream;
     }
 }
+/**
+ * Standalone, after-the-fact reconciliation for the no-idempotency problem.
+ *
+ * `orders place` reconciles automatically the instant a placement fails (see
+ * {@link reconcileAfterFailure}), but that check lives and dies with the
+ * process — a killed shell, a crashed script, a slept laptop and it is gone.
+ * This re-runs it on demand. Given the unique tag every order carries, it
+ * answers the only question that matters after an ambiguous failure — "did it
+ * actually reach Kite?" — so you know whether it is safe to place again.
+ *
+ * With a tag, it looks that tag up. With none, it lists the orders this CLI
+ * placed today (those carrying the {@link CLI_TAG_PREFIX} prefix), so you can
+ * still find one whose exact tag you did not capture. It is a query, not a
+ * mutation: it exits 0 on any clean answer, and the `--json` `placed` flag is
+ * the machine-readable verdict.
+ */
+async function reconcileOrders(ctx, _opts, command) {
+    ctx.requireSession();
+    const { io } = ctx;
+    const tag = command.args[0];
+    if (tag) {
+        const matches = await ctx.api.findOrderByTag(tag, ctx.signal);
+        if (io.json) {
+            io.writeJson({ tag, placed: matches.length > 0, order_ids: matches.map((o) => o.order_id), orders: matches });
+            return;
+        }
+        if (matches.length === 0) {
+            io.warn(`No order found for tag ${io.bold(tag)}.`);
+            io.info('If a placement looked like it failed, it most likely did not reach Kite — but check `kite orders list` before retrying, in case it simply has not appeared yet.');
+            return;
+        }
+        io.success(`Found ${matches.length === 1 ? 'an order' : `${matches.length} orders`} for tag ${io.bold(tag)}:`);
+        io.line(renderTableFor(ctx, matches, reconcileColumns()));
+        io.info('If placing this order looked like it failed, it went through — do not place it again.');
+        return;
+    }
+    const mine = (await ctx.api.getOrders(ctx.signal)).filter(hasCliTag);
+    printTable(io, mine, reconcileColumns(), mine, {
+        compact: ctx.config.output.compact,
+        empty: `No orders tagged by this CLI today (looking for the \`${CLI_TAG_PREFIX}\` prefix).`,
+    });
+    if (mine.length > 0 && !io.json) {
+        io.info('Reconcile a specific one with `kite orders reconcile <tag>`.');
+    }
+}
+/** True if this order carries a CLI-generated tag (see {@link CLI_TAG_PREFIX}). */
+function hasCliTag(order) {
+    if (order.tag?.startsWith(CLI_TAG_PREFIX))
+        return true;
+    return order.tags?.some((t) => t.startsWith(CLI_TAG_PREFIX)) ?? false;
+}
+function reconcileColumns() {
+    return [
+        { header: 'Time', value: (o) => timeOnly(o.order_timestamp) },
+        { header: 'Order ID', value: (o, io) => io.dim(o.order_id) },
+        { header: 'Symbol', value: (o, io) => io.bold(o.tradingsymbol ?? '—') },
+        {
+            header: 'Side',
+            value: (o, io) => o.transaction_type === 'BUY' ? io.green('BUY') : o.transaction_type === 'SELL' ? io.red('SELL') : '—',
+        },
+        {
+            header: 'Qty',
+            value: (o) => `${quantity(o.filled_quantity ?? 0)}/${quantity(o.quantity ?? 0)}`,
+            align: 'right',
+        },
+        { header: 'Status', value: (o, io) => colourStatus(io, o.status) },
+        { header: 'Tag', value: (o) => o.tag ?? '—' },
+    ];
+}
 // ---------------------------------------------------------------------------
 // Modify / cancel
 // ---------------------------------------------------------------------------

package/dist/commands/register.d.ts

@@ -0,0 +1,25 @@
+import type { Command } from 'commander';
+import type { Runner } from './types.js';
+/**
+ * Command wiring, factored out of run.ts so there is a single source of truth
+ * for the command tree.
+ *
+ * run() consumes this to build the live program; `kite completion` consumes it
+ * with a no-op runner to introspect command and flag names for shell
+ * completions. Keeping both on the same registration path means a new command
+ * or flag is completable the moment it is added, with nothing to keep in sync.
+ */
+/**
+ * Attach the global options every command inherits. Split from the name /
+ * version / output wiring in run.ts, which is invocation-specific, so an
+ * introspection-only program can still enumerate the same global flags.
+ */
+export declare function applyGlobalOptions(program: Command): Command;
+/**
+ * Register every command group on `program`, grouped for a readable `--help`.
+ *
+ * The `run` runner wraps each handler with context construction and error
+ * reporting in the real CLI; completion passes a no-op that only needs the
+ * command definitions, not their behaviour.
+ */
+export declare function registerCommands(program: Command, run: Runner): Promise<void>;

package/dist/commands/register.js

@@ -0,0 +1,78 @@
+/**
+ * Command wiring, factored out of run.ts so there is a single source of truth
+ * for the command tree.
+ *
+ * run() consumes this to build the live program; `kite completion` consumes it
+ * with a no-op runner to introspect command and flag names for shell
+ * completions. Keeping both on the same registration path means a new command
+ * or flag is completable the moment it is added, with nothing to keep in sync.
+ */
+/**
+ * Attach the global options every command inherits. Split from the name /
+ * version / output wiring in run.ts, which is invocation-specific, so an
+ * introspection-only program can still enumerate the same global flags.
+ */
+export function applyGlobalOptions(program) {
+    return (program
+        .option('--json', 'Emit JSON instead of formatted tables')
+        .option('--color <when>', 'Colour output: auto, always, or never')
+        // Deliberately no `-q` short form: it would shadow `-q, --quantity` on the
+        // order and GTT subcommands, which is typed far more often than --quiet.
+        .option('--quiet', 'Suppress informational messages')
+        .option('--debug', 'Print redacted request diagnostics to stderr')
+        .option('--env <env>', 'Environment: production or sandbox')
+        .option('--profile <name>', 'Account profile to use (see `kite profiles`)')
+        .option('-y, --yes', 'Skip confirmation prompts (use with care)')
+        .option('--dry-run', 'Show what would happen without sending anything to Kite'));
+}
+/**
+ * Register every command group on `program`, grouped for a readable `--help`.
+ *
+ * The `run` runner wraps each handler with context construction and error
+ * reporting in the real CLI; completion passes a no-op that only needs the
+ * command definitions, not their behaviour.
+ */
+export async function registerCommands(program, run) {
+    // Imported here rather than at module top so a single invocation only pays for
+    // parsing the command modules once run() (or completion) actually asks for
+    // them, not on every `import` of this file.
+    const { authCommands } = await import('./auth.js');
+    const { profileCommands } = await import('./profiles.js');
+    const { portfolioCommands } = await import('./portfolio.js');
+    const { marketCommands } = await import('./market.js');
+    const { orderCommands } = await import('./orders.js');
+    const { gttCommands } = await import('./gtt.js');
+    const { alertCommands } = await import('./alerts.js');
+    const { marginCommands } = await import('./margins.js');
+    const { mfCommands } = await import('./mf.js');
+    const { watchCommands } = await import('./watch.js');
+    const { configCommands } = await import('./config.js');
+    const { doctorCommands } = await import('./doctor.js');
+    const { completionCommands } = await import('./completion.js');
+    const { mcpCommands } = await import('./mcp.js');
+    // commandsGroup applies to every command registered after it, so the group
+    // is set immediately before each block. With ~25 commands this is the
+    // difference between a readable --help and a wall of text.
+    program.commandsGroup('Account:');
+    authCommands(program, run);
+    profileCommands(program, run);
+    program.commandsGroup('Portfolio:');
+    portfolioCommands(program, run);
+    program.commandsGroup('Mutual funds:');
+    mfCommands(program, run);
+    program.commandsGroup('Market data:');
+    marketCommands(program, run);
+    program.commandsGroup('Trading:');
+    orderCommands(program, run);
+    gttCommands(program, run);
+    alertCommands(program, run);
+    marginCommands(program, run);
+    program.commandsGroup('Streaming:');
+    watchCommands(program, run);
+    program.commandsGroup('Integrations:');
+    mcpCommands(program, run);
+    program.commandsGroup('Settings:');
+    configCommands(program, run);
+    doctorCommands(program, run);
+    completionCommands(program, run);
+}

package/dist/core/auth.d.ts

@@ -59,6 +59,15 @@ export declare function waitForCallback(opts: CallbackServerOptions): {
     close: () => void;
 };
 export declare function redirectUrlFor(port: number, path: string): string;
+/**
+ * Copy text to the OS clipboard, returning whether it succeeded.
+ *
+ * Like {@link openBrowser}, the text is piped to a fixed binary's stdin — never
+ * through a shell and never as an argv element — so a URL's `&`/`=` cannot
+ * become word-splitting or command injection. On Linux there is no single
+ * clipboard tool, so we try the common ones in turn (Wayland first, then X11).
+ */
+export declare function copyToClipboard(text: string): Promise<boolean>;
 /**
  * Open a URL in the user's default browser.
  *

package/dist/core/auth.js

@@ -175,6 +175,45 @@ function escapeHtml(value) {
 export function redirectUrlFor(port, path) {
     return `http://127.0.0.1:${port}${path}`;
 }
+/**
+ * Copy text to the OS clipboard, returning whether it succeeded.
+ *
+ * Like {@link openBrowser}, the text is piped to a fixed binary's stdin — never
+ * through a shell and never as an argv element — so a URL's `&`/`=` cannot
+ * become word-splitting or command injection. On Linux there is no single
+ * clipboard tool, so we try the common ones in turn (Wayland first, then X11).
+ */
+export async function copyToClipboard(text) {
+    const candidates = process.platform === 'darwin'
+        ? [['pbcopy', []]]
+        : process.platform === 'win32'
+            ? [['clip', []]]
+            : [
+                ['wl-copy', []],
+                ['xclip', ['-selection', 'clipboard']],
+                ['xsel', ['--clipboard', '--input']],
+            ];
+    for (const [command, args] of candidates) {
+        if (await pipeToCommand(command, args, text))
+            return true;
+    }
+    return false;
+}
+/** Spawn `command`, write `text` to its stdin, resolve true on a clean exit. */
+function pipeToCommand(command, args, text) {
+    return import('node:child_process').then(({ spawn }) => new Promise((resolve) => {
+        try {
+            const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'ignore'], shell: false });
+            child.on('error', () => resolve(false));
+            child.on('close', (code) => resolve(code === 0));
+            child.stdin.on('error', () => resolve(false));
+            child.stdin.end(text);
+        }
+        catch {
+            resolve(false);
+        }
+    }));
+}
 /**
  * Open a URL in the user's default browser.
  *

package/dist/core/client.js

@@ -177,7 +177,14 @@ export class KiteClient {
             return new KiteCliError('Cancelled.', ExitCode.Aborted);
         }
         const message = err instanceof Error ? err.message : String(err);
-        return new NetworkError(`Could not reach Kite: ${redactString(message)}`, 'Check your network connection.');
+        // undici's fetch wraps the actual failure (ECONNRESET, ENOTFOUND, a TLS
+        // error, ...) in `cause` and sets `message` to the unhelpful constant
+        // "fetch failed" — surface the cause too, or every transient network
+        // problem looks identical and undebuggable.
+        const cause = err instanceof Error ? err.cause : undefined;
+        const causeMessage = cause instanceof Error ? cause.message : cause !== undefined ? String(cause) : undefined;
+        const detail = causeMessage && causeMessage !== message ? `${message}: ${causeMessage}` : message;
+        return new NetworkError(`Could not reach Kite: ${redactString(detail)}`, 'Check your network connection.');
     }
     handleResponse(response, text, schema, url) {
         let payload;

package/dist/core/mcp.d.ts

@@ -0,0 +1,56 @@
+import type { z } from 'zod';
+/** A tool the agent may call. `schema` validates the arguments before dispatch. */
+export interface McpTool<S extends z.ZodType = z.ZodType> {
+    name: string;
+    description: string;
+    schema: S;
+    /** JSON Schema for the arguments, advertised in `tools/list`. */
+    inputSchema: Record<string, unknown>;
+    handler: (args: z.infer<S>, signal?: AbortSignal) => Promise<unknown> | unknown;
+}
+export interface McpServerOptions {
+    name: string;
+    version: string;
+    tools: McpTool[];
+    /** Aborting this stops the serve loop after the in-flight message. */
+    signal?: AbortSignal | undefined;
+}
+interface JsonRpcRequest {
+    jsonrpc?: unknown;
+    id?: string | number | null;
+    method?: unknown;
+    params?: unknown;
+}
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export declare class McpServer {
+    private readonly tools;
+    private readonly name;
+    private readonly version;
+    private readonly signal;
+    constructor(opts: McpServerOptions);
+    /**
+     * Handle a single decoded JSON-RPC message.
+     *
+     * Returns the response to write back, or `null` for a notification (a request
+     * with no `id`), which by JSON-RPC must never be answered — even on error.
+     */
+    handle(request: JsonRpcRequest): Promise<JsonRpcResponse | null>;
+    private initializeResult;
+    private toolList;
+    private callTool;
+    /**
+     * Read newline-delimited JSON-RPC from `input` and write responses to
+     * `output`, until the input closes or the abort signal fires.
+     */
+    serve(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): Promise<void>;
+}
+export {};