@secapi/cli 0.4.0 → 0.5.0

package/README.md

@@ -8,6 +8,23 @@ Command-line interface for SEC API factor data, SEC filings, financial statement
 npm install -g @secapi/cli
 ```
 
+## Connect an agent
+
+Wire the hosted MCP server into your agent client in one command:
+
+```bash
+secapi init --client claude-code      # prints the `claude mcp add` command
+secapi init --client cursor           # writes .cursor/mcp.json
+secapi init --client claude-desktop   # writes the Claude Desktop config
+secapi init --client windsurf         # writes ~/.codeium/windsurf/mcp_config.json
+secapi init --client project          # writes ./.mcp.json
+secapi init --client cursor --print   # dry-run: print the config, write nothing
+```
+
+`secapi init` reads your key from `SECAPI_API_KEY` (or `--api-key-stdin`) and never
+accepts it as an argv flag. `secapi agent-context` prints a machine-readable JSON
+description of the whole CLI surface so an agent can learn the tool in one call.
+
 ## Configuration
 
 ```bash

package/dist/index.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 
 // src/generated-contracts/agent-prompts.ts
 var AGENT_PROMPT_PERSONAS = [
@@ -25558,6 +25560,140 @@ async function main() {
     }));
     return;
   }
+  if (group === "init" || group === "agents" && command === "setup") {
+    const mcpUrl = `${baseUrl.replace(/\/+$/, "")}/mcp`;
+    const initKeySource = hasFlag(STDIN_FLAG_NAME) ? credentials.apiKey : envCredential("SECAPI_API_KEY");
+    const literalKey = initKeySource ?? "YOUR_API_KEY";
+    const hasRealKey = Boolean(initKeySource);
+    const dryRun = hasFlag("--print") || hasFlag("--dry-run");
+    const positional = group === "init" && command && !command.startsWith("-") ? command : undefined;
+    const clientFlag = getFlag("--client");
+    const requested = clientFlag && !clientFlag.startsWith("-") ? clientFlag : positional;
+    const claudeDesktopPath = () => {
+      const home = homedir();
+      if (process.platform === "darwin")
+        return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+      if (process.platform === "win32")
+        return join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+      return join(home, ".config", "Claude", "claude_desktop_config.json");
+    };
+    const clients = {
+      "claude-code": { kind: "command" },
+      "claude-desktop": { kind: "file", urlKey: "url", httpType: true, keyValue: literalKey, committable: false, path: claudeDesktopPath },
+      cursor: { kind: "file", urlKey: "url", httpType: false, keyValue: "${SECAPI_API_KEY}", committable: true, path: () => join(process.cwd(), ".cursor", "mcp.json") },
+      windsurf: { kind: "file", urlKey: "serverUrl", httpType: false, keyValue: "${env:SECAPI_API_KEY}", committable: false, path: () => join(homedir(), ".codeium", "windsurf", "mcp_config.json") },
+      project: { kind: "file", urlKey: "url", httpType: true, keyValue: "${SECAPI_API_KEY}", committable: true, path: () => join(process.cwd(), ".mcp.json") }
+    };
+    const names = Object.keys(clients).join(", ");
+    if (!requested) {
+      process.stdout.write(`Usage: secapi init --client <${names}> [--print]
+
+Writes the SEC API hosted-MCP config (${mcpUrl}, x-api-key) for your agent client.
+Provide your API key via SECAPI_API_KEY (or ${STDIN_FLAG_NAME}); it is never read from an argv flag.
+`);
+      return;
+    }
+    const spec = clients[requested];
+    if (!spec)
+      throw new Error(`Unknown client '${requested}'. Supported: ${names}`);
+    if (spec.kind === "command") {
+      process.stdout.write(`Add SEC API to Claude Code:
+
+  claude mcp add --transport http secapi ${mcpUrl} --header "x-api-key: $SECAPI_API_KEY"
+`);
+      if (!hasRealKey)
+        process.stdout.write(`
+Set SECAPI_API_KEY in your environment first.
+`);
+      return;
+    }
+    const filePath = spec.path();
+    let config2 = {};
+    if (existsSync(filePath)) {
+      let parsed;
+      try {
+        parsed = JSON.parse(readFileSync(filePath, "utf8"));
+      } catch {
+        throw new Error(`Existing config at ${filePath} is not valid JSON; fix or move it before running init.`);
+      }
+      if (Array.isArray(parsed) || typeof parsed !== "object" || parsed === null) {
+        throw new Error(`Existing config at ${filePath} is not a JSON object; fix or move it before running init.`);
+      }
+      config2 = parsed;
+    }
+    const existingServers = config2.mcpServers;
+    if (existingServers !== undefined && (typeof existingServers !== "object" || existingServers === null || Array.isArray(existingServers))) {
+      throw new Error(`Existing "mcpServers" in ${filePath} is not an object; fix or move it before running init.`);
+    }
+    const servers = existingServers ? existingServers : {};
+    servers.secapi = {
+      ...spec.httpType ? { type: "http" } : {},
+      [spec.urlKey]: mcpUrl,
+      headers: { "x-api-key": spec.keyValue }
+    };
+    config2.mcpServers = servers;
+    const rendered = `${JSON.stringify(config2, null, 2)}
+`;
+    if (dryRun) {
+      process.stdout.write(`# ${filePath}
+${rendered}`);
+      return;
+    }
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, rendered, { mode: 384 });
+    chmodSync(filePath, 384);
+    process.stdout.write(`Wrote SEC API MCP config for ${requested} to ${filePath}
+`);
+    if (spec.keyValue.startsWith("$")) {
+      process.stdout.write(`Set SECAPI_API_KEY in your environment so ${requested} can resolve the key.
+`);
+    } else if (!hasRealKey) {
+      process.stdout.write(`Replace YOUR_API_KEY in that file with your key (or set SECAPI_API_KEY and re-run).
+`);
+    }
+    if (spec.committable) {
+      process.stdout.write(`Note: ${filePath} can be committed — it uses an env-var reference, not your literal key.
+`);
+    }
+    process.stdout.write(`Restart ${requested} to load the server.
+`);
+    return;
+  }
+  if (group === "agent-context" || group === "agents" && command === "context") {
+    print({
+      object: "agent_context",
+      cli: { binaries: ["secapi", "omni-sec"], version: cliVersion() },
+      baseUrl,
+      mcpUrl: `${baseUrl.replace(/\/+$/, "")}/mcp`,
+      docs: "https://docs.secapi.ai",
+      agentsPage: "https://secapi.ai/agents",
+      auth: {
+        header: "x-api-key",
+        note: "Authenticate with the x-api-key header. Never send the API key as Authorization: Bearer.",
+        envVars: ["SECAPI_API_KEY", "SECAPI_OPERATOR_API_KEY", "SECAPI_BEARER_TOKEN (WorkOS bearer, not an API key)"],
+        stdin: [STDIN_FLAG_NAME, STDIN_BEARER_FLAG_NAME]
+      },
+      install: {
+        mcp: `secapi init --client <claude-code|claude-desktop|cursor|windsurf|project>`,
+        skills: "npx skills add secapi-ai/secapi-skills --global"
+      },
+      commandGroups: [
+        { group: "account", commands: ["health", "me", "org show", "billing show", "usage show", "limits show", "api-keys list", "api-keys create --label <l> --scopes <s>"] },
+        { group: "agent", commands: ["agent bootstrap-token --label <l> --scopes <s> --ttl-seconds <n>", "agent bootstrap --token <agbt_...>"] },
+        { group: "agents", commands: ["agents personas", "agents prompts list [--persona <p>] [--include-v2] [--json]", "agents prompts read <id>", "agents prompts copy <id>", "agents setup --client <name>", "agents context"] },
+        { group: "entities", commands: ["entities resolve --ticker <t> | --name <n> | --cik <c>"] },
+        { group: "filings", commands: ["filings search --ticker <t> --form <f>", "filings latest --ticker <t> --form <f>", "sections get --ticker <t> --form 10-K --section item_1a"] },
+        { group: "factors", commands: ["factors exposures --symbols <list>", "factors decomposition --symbol <t>", "factors screen --keys <list>", "factors valuations --keys <list>"] },
+        { group: "setup", commands: ["init --client <claude-code|claude-desktop|cursor|windsurf|project> [--print]", "agent-context"] }
+      ],
+      conventions: {
+        output: "JSON to stdout by default; human-readable when stdout is a TTY for agents/personas commands.",
+        correlation: "Request-Id header on every response.",
+        guardrails: "Check GET /v1/billing and POST /v1/billing/quote before expensive or repeated workflows."
+      }
+    });
+    return;
+  }
   const commandHelpLines = [
     "SEC API CLI",
     "Preferred binary: secapi",
@@ -25576,6 +25712,12 @@ async function main() {
     "  secapi agent bootstrap-token --label ci --scopes read:sec --ttl-seconds 900",
     "  secapi agent bootstrap --token agbt_... --label first-agent-key",
     "",
+    "  # Connect an agent (one-command MCP install)",
+    "  secapi init --client claude-code        # prints the `claude mcp add` command",
+    "  secapi init --client cursor             # writes .cursor/mcp.json",
+    "  secapi init --client claude-desktop --print   # dry-run the config",
+    "  secapi agent-context                    # machine-readable CLI surface for agents",
+    "",
     "  # Agent prompt library",
     "  secapi agents personas",
     "  secapi agents prompts list",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secapi/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "SEC API CLI for SEC data shaped for investors and agents",
   "type": "module",
   "bin": {