@pungoyal/kite-cli 0.3.0 → 0.5.0

package/dist/core/mcp.js

@@ -0,0 +1,166 @@
+import { createInterface } from 'node:readline';
+import { redact, redactString } from './redact.js';
+/**
+ * A minimal Model Context Protocol (MCP) server over stdio.
+ *
+ * MCP lets an LLM agent (Claude and others) call tools exposed by a local
+ * process. This server exposes Kite's *read* endpoints so an agent can inspect a
+ * portfolio, quotes and the orderbook — never place, modify or cancel anything.
+ *
+ * Two deliberate design choices, both flowing from this repo's own principles:
+ *
+ *  - **Hand-rolled, not the official SDK.** A minimal dependency tree is a
+ *    security property here (see scripts/check-deps.mjs), and the SDK pulls a
+ *    heavy transitive closure. The stdio transport is newline-delimited JSON-RPC
+ *    2.0 — small enough to implement directly and unit-test in full.
+ *  - **Read-only.** A money-moving command must render the resolved order and
+ *    obtain confirmation (see src/safety.ts), and an MCP server has no terminal
+ *    to confirm at. Rather than weaken that invariant, writes are simply not
+ *    exposed. An agent that wants to trade must hand back to a human at a TTY.
+ *
+ * The transport framing is newline-delimited JSON: one JSON message per line,
+ * no embedded newlines, no Content-Length headers (that is the HTTP transport,
+ * not stdio).
+ */
+/** Latest protocol revision this server speaks. Echoed back if a client asks. */
+const DEFAULT_PROTOCOL_VERSION = '2025-06-18';
+// Standard JSON-RPC 2.0 error codes.
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INTERNAL_ERROR = -32603;
+export class McpServer {
+    tools;
+    name;
+    version;
+    signal;
+    constructor(opts) {
+        this.tools = opts.tools;
+        this.name = opts.name;
+        this.version = opts.version;
+        this.signal = opts.signal;
+    }
+    /**
+     * 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.
+     */
+    async handle(request) {
+        const isNotification = request?.id === undefined;
+        const id = request?.id ?? null;
+        if (request?.jsonrpc !== '2.0' || typeof request.method !== 'string') {
+            return isNotification ? null : error(id, INVALID_REQUEST, 'Invalid Request');
+        }
+        const { method, params } = request;
+        try {
+            switch (method) {
+                case 'initialize':
+                    return ok(id, this.initializeResult(params));
+                case 'ping':
+                    return ok(id, {});
+                case 'tools/list':
+                    return ok(id, { tools: this.toolList() });
+                case 'tools/call':
+                    return ok(id, await this.callTool(params));
+                default:
+                    // Unknown notifications (e.g. notifications/initialized, .../cancelled)
+                    // are ignored; unknown requests get a method-not-found error.
+                    return isNotification ? null : error(id, METHOD_NOT_FOUND, `Method not found: ${method}`);
+            }
+        }
+        catch (err) {
+            // A thrown error here is an internal fault, not a tool-level failure (those
+            // are reported in-band via isError). Redact: the message could echo input.
+            return isNotification ? null : error(id, INTERNAL_ERROR, redactString(messageOf(err)));
+        }
+    }
+    initializeResult(params) {
+        // Speak the client's requested revision when it names one, so we interoperate
+        // with older clients; otherwise advertise our latest.
+        const requested = params?.protocolVersion;
+        return {
+            protocolVersion: typeof requested === 'string' ? requested : DEFAULT_PROTOCOL_VERSION,
+            capabilities: { tools: {} },
+            serverInfo: { name: this.name, version: this.version },
+        };
+    }
+    toolList() {
+        return this.tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }));
+    }
+    async callTool(params) {
+        const name = params?.name;
+        const tool = this.tools.find((t) => t.name === name);
+        if (!tool) {
+            return toolError(`Unknown tool: ${typeof name === 'string' ? name : String(name)}`);
+        }
+        const rawArgs = params.arguments ?? {};
+        const parsed = tool.schema.safeParse(rawArgs);
+        if (!parsed.success) {
+            return toolError(`Invalid arguments for ${tool.name}: ${redactString(parsed.error.message)}`);
+        }
+        try {
+            const data = await tool.handler(parsed.data, this.signal);
+            // Redact tool output too: this is a fresh egress channel, and a Kite
+            // response or error could carry a value we treat as secret. (Redaction
+            // invariant — see src/core/redact.ts.)
+            return { content: [{ type: 'text', text: JSON.stringify(redact(data)) }] };
+        }
+        catch (err) {
+            // Tool failures are surfaced to the model in-band, so it can react (retry a
+            // different symbol, tell the user to log in), not as a transport error.
+            return toolError(redactString(messageOf(err)));
+        }
+    }
+    /**
+     * Read newline-delimited JSON-RPC from `input` and write responses to
+     * `output`, until the input closes or the abort signal fires.
+     */
+    async serve(input, output) {
+        const rl = createInterface({ input, crlfDelay: Number.POSITIVE_INFINITY });
+        const onAbort = () => rl.close();
+        this.signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            for await (const line of rl) {
+                const trimmed = line.trim();
+                if (trimmed === '')
+                    continue;
+                let response;
+                let request;
+                try {
+                    request = JSON.parse(trimmed);
+                }
+                catch {
+                    response = error(null, PARSE_ERROR, 'Parse error');
+                    output.write(`${JSON.stringify(response)}\n`);
+                    continue;
+                }
+                response = await this.handle(request);
+                if (response)
+                    output.write(`${JSON.stringify(response)}\n`);
+                if (this.signal?.aborted)
+                    break;
+            }
+        }
+        finally {
+            this.signal?.removeEventListener('abort', onAbort);
+            rl.close();
+        }
+    }
+}
+function ok(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+function error(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}
+function toolError(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export { type ClientOptions, KiteClient, setDispatcher, } from './core/client.js
 export { type Endpoints, type Environment, endpointsFor, SANDBOX_CREDENTIALS, } from './core/config.js';
 export { AuthRequiredError, ExitCode, KiteApiError, KiteCliError, type KiteErrorType, NetworkError, UsageError, } from './core/errors.js';
 export { InstrumentStore, parseInstrumentKey, parseInstrumentsCsv, } from './core/instruments.js';
+export { McpServer, type McpServerOptions, type McpTool, } from './core/mcp.js';
 export { DEFAULT_PROFILE, getProfile, listProfileNames, type ResolvedProfile, resolveProfile, resolveTradingConfig, SANDBOX_PROFILE, storagePrefixFor, } from './core/profiles.js';
 export { ORDER_LIMITS, type RateCategory, RateLimiter, } from './core/ratelimit.js';
 export { maskSecret, redact, redactString, redactUrl, registerSecret, } from './core/redact.js';

package/dist/index.js

@@ -11,6 +11,7 @@ export { KiteClient, setDispatcher, } from './core/client.js';
 export { endpointsFor, SANDBOX_CREDENTIALS, } from './core/config.js';
 export { AuthRequiredError, ExitCode, KiteApiError, KiteCliError, NetworkError, UsageError, } from './core/errors.js';
 export { InstrumentStore, parseInstrumentKey, parseInstrumentsCsv, } from './core/instruments.js';
+export { McpServer, } from './core/mcp.js';
 export { DEFAULT_PROFILE, getProfile, listProfileNames, resolveProfile, resolveTradingConfig, SANDBOX_PROFILE, storagePrefixFor, } from './core/profiles.js';
 export { ORDER_LIMITS, RateLimiter, } from './core/ratelimit.js';
 export { maskSecret, redact, redactString, redactUrl, registerSecret, } from './core/redact.js';

package/dist/run.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { Command, CommanderError } from 'commander';
+import { applyGlobalOptions, registerCommands } from './commands/register.js';
 import { createContext } from './context.js';
 import { AbortedError, ExitCode, KiteCliError } from './core/errors.js';
 import { redactString } from './core/redact.js';
@@ -34,18 +35,8 @@ export async function run(opts = {}) {
     let exitCode = ExitCode.Ok;
     program
         .name('kite')
-        .description('Unofficial command-line interface for the Zerodha Kite Connect API (not affiliated with Zerodha)')
+        .description('Unofficial, safety-first CLI for the Zerodha Kite Connect v3 API (not affiliated with Zerodha)')
         .version(VERSION, '-v, --version')
-        .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')
         .showHelpAfterError('(run `kite --help` for usage)')
         .configureOutput({
         writeOut: (str) => (opts.streams?.stdout ?? process.stdout).write(str),
@@ -54,6 +45,7 @@ export async function run(opts = {}) {
         // Throw instead of calling process.exit, so `run()` stays testable and
         // always returns its exit code.
         .exitOverride();
+    applyGlobalOptions(program);
     /** Wraps a handler with context construction and error reporting. */
     const withContext = (handler) => async (...args) => {
         // Commander passes (…arguments, options, command).
@@ -68,40 +60,11 @@ export async function run(opts = {}) {
             exitCode = reportError(err, ctx.io);
         }
     };
-    // Registered lazily so a bare `kite quote` never pays to import the
-    // dashboard renderer, the ticker, or the prompt library.
-    const { authCommands } = await import('./commands/auth.js');
-    const { profileCommands } = await import('./commands/profiles.js');
-    const { portfolioCommands } = await import('./commands/portfolio.js');
-    const { marketCommands } = await import('./commands/market.js');
-    const { orderCommands } = await import('./commands/orders.js');
-    const { gttCommands } = await import('./commands/gtt.js');
-    const { alertCommands } = await import('./commands/alerts.js');
-    const { marginCommands } = await import('./commands/margins.js');
-    const { mfCommands } = await import('./commands/mf.js');
-    const { watchCommands } = await import('./commands/watch.js');
-    const { configCommands } = await import('./commands/config.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, withContext);
-    profileCommands(program, withContext);
-    program.commandsGroup('Portfolio:');
-    portfolioCommands(program, withContext);
-    program.commandsGroup('Mutual funds:');
-    mfCommands(program, withContext);
-    program.commandsGroup('Market data:');
-    marketCommands(program, withContext);
-    program.commandsGroup('Trading:');
-    orderCommands(program, withContext);
-    gttCommands(program, withContext);
-    alertCommands(program, withContext);
-    marginCommands(program, withContext);
-    program.commandsGroup('Streaming:');
-    watchCommands(program, withContext);
-    program.commandsGroup('Settings:');
-    configCommands(program, withContext);
+    // Registered through the shared registration path (see commands/register.ts)
+    // so run() and `kite completion` build the exact same command tree. Modules
+    // are still imported lazily inside registerCommands, so a bare `kite quote`
+    // never pays to parse the dashboard renderer or the ticker up front.
+    await registerCommands(program, withContext);
     program.addHelpText('after', `
 Examples:
   $ kite login                                  Authenticate and store a session

package/dist/safety.d.ts

@@ -76,6 +76,14 @@ export declare function confirmAction(ctx: Context, opts: ConfirmOptions): Promi
  *
  * Kite caps `tag` at 20 alphanumeric characters.
  */
+/**
+ * Prefix on every tag the CLI generates for an order it places.
+ *
+ * It lets the orderbook be filtered back to orders this tool placed — which is
+ * what `orders reconcile` (with no tag) uses to surface CLI-issued orders. Only
+ * the auto-generated tag carries it; a user-supplied `--tag` is kept verbatim.
+ */
+export declare const CLI_TAG_PREFIX = "kc";
 export declare function generateOrderTag(prefix?: string): string;
 /**
  * Build the tag actually sent to Kite, guaranteeing uniqueness even when the

package/dist/safety.js

@@ -138,7 +138,15 @@ function accountLine(ctx) {
  *
  * Kite caps `tag` at 20 alphanumeric characters.
  */
-export function generateOrderTag(prefix = 'kc') {
+/**
+ * Prefix on every tag the CLI generates for an order it places.
+ *
+ * It lets the orderbook be filtered back to orders this tool placed — which is
+ * what `orders reconcile` (with no tag) uses to surface CLI-issued orders. Only
+ * the auto-generated tag carries it; a user-supplied `--tag` is kept verbatim.
+ */
+export const CLI_TAG_PREFIX = 'kc';
+export function generateOrderTag(prefix = CLI_TAG_PREFIX) {
     const random = randomBytes(6).toString('hex');
     const stamp = Date.now().toString(36);
     return `${prefix}${stamp}${random}`.slice(0, 20);

package/package.json

@@ -1,16 +1,21 @@
 {
   "name": "@pungoyal/kite-cli",
-  "version": "0.3.0",
-  "description": "Unofficial command-line interface for the Zerodha Kite Connect API — not affiliated with or endorsed by Zerodha",
+  "version": "0.5.0",
+  "description": "Unofficial, safety-first CLI (and library) for the Zerodha Kite Connect v3 API — scriptable JSON, live streaming, and confirmations on anything that moves money. Not affiliated with or endorsed by Zerodha.",
   "keywords": [
     "zerodha",
     "kite",
     "kiteconnect",
+    "kite-connect",
     "trading",
+    "trading-api",
+    "algo-trading",
     "stocks",
     "cli",
+    "terminal",
     "nse",
-    "bse"
+    "bse",
+    "nifty"
   ],
   "license": "MIT",
   "author": "Puneet Goyal",