@kumokodo/kodori-sdk

Official TypeScript SDK for Kodori — the AI-native document management system by KumoKodo.

Wraps the public REST API at /api/v1 and provides helpers for connecting to the public Model Context Protocol endpoint at /api/mcp.

Install

npm install @kumokodo/kodori-sdk
# or
pnpm add @kumokodo/kodori-sdk
# or
yarn add @kumokodo/kodori-sdk

Requires Node.js 18+ (or any runtime with globalThis.fetch).

Authentication

Mint an API key at https://kodori.ai/api-keys. The plaintext is shown exactly once at creation. Pick the scopes you need:

• search:read — always granted (read documents, search, list collections)
• documents:write — rename, change sensitivity, patch metadata
• documents:delete — soft-delete (tombstone) and restore
• collections:write — create collections, add or remove pinned members

The same key authenticates against the REST API AND the public MCP endpoint.

REST quickstart

import { KodoriClient } from '@kumokodo/kodori-sdk';

const kodori = new KodoriClient({ apiKey: process.env.KODORI_API_KEY! });

// Identity probe
const me = await kodori.me.get();
console.log(me.email, me.scopes);

// Hybrid search (keyword + semantic, RRF-fused)
const { hits } = await kodori.search.run({
  query: 'indemnity clause from 2024',
  limit: 10,
});

// Read a document's metadata + extracted text
for (const hit of hits) {
  const doc = await kodori.documents.get(hit.documentId, { limit: 4000 });
  console.log(doc.displayName, doc.textSlice?.slice(0, 200));
}

// Mutating calls (require the matching scope)
await kodori.documents.rename(hit.documentId, 'Smith NDA — final');
await kodori.documents.setSensitivity(
  hit.documentId,
  'regulated',
  'Contains SSN per DLP scan',
);

Permission-trimming

Every endpoint runs your tenant's canReadDocument SQL gate against the issuing user's ACL. Your integration sees exactly what that user sees — no more, no less. There is no privileged "service-account" mode.

Error handling

Non-2xx responses throw KodoriApiError:

import { KodoriClient, KodoriApiError } from '@kumokodo/kodori-sdk';

try {
  await kodori.documents.tombstone(id, 'Duplicate of another upload');
} catch (err) {
  if (err instanceof KodoriApiError) {
    if (err.code === 'hold-deny') {
      console.warn('Document is on legal hold:', err.details);
    } else if (err.status === 403) {
      console.warn('Key missing scope:', err.message);
    } else {
      throw err;
    }
  }
}

Public MCP server

Kodori speaks the Model Context Protocol natively. Any MCP-conformant client (Claude Desktop, Cursor, ChatGPT desktop, custom tooling) can connect to /api/mcp with your Kodori API key and call the entire 60+ tool catalog the internal agent uses.

The SDK ships helpers under /mcp so you don't have to remember endpoint URLs or header shapes:

import {
  mcpEndpointUrl,
  bearerAuthHeader,
  claudeDesktopConfig,
  cursorMcpConfig,
} from '@kumokodo/kodori-sdk/mcp';

// Generate the exact JSON snippet for ~/Library/Application Support/Claude/claude_desktop_config.json
console.log(JSON.stringify(
  claudeDesktopConfig({ apiKey: process.env.KODORI_API_KEY! }),
  null,
  2,
));

// Or the shape Cursor's MCP-server settings UI accepts
console.log(cursorMcpConfig({ apiKey: process.env.KODORI_API_KEY! }));

// Raw plumbing for a custom JSON-RPC client
const url = mcpEndpointUrl();
const headers = bearerAuthHeader(process.env.KODORI_API_KEY!);

For a full programmatic MCP client, pair the SDK helpers with Anthropic's @modelcontextprotocol/sdk:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { mcpEndpointUrl, bearerAuthHeader } from '@kumokodo/kodori-sdk/mcp';

const transport = new StreamableHTTPClientTransport(new URL(mcpEndpointUrl()), {
  requestInit: { headers: bearerAuthHeader(process.env.KODORI_API_KEY!) },
});

const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(`Connected to Kodori; ${tools.length} tools available`);

Self-hosted / staging deployments

Pass baseUrl to point at a non-default origin:

const kodori = new KodoriClient({
  apiKey: process.env.KODORI_API_KEY!,
  baseUrl: 'https://kodori.staging.acme.com',
});

The MCP helpers accept the same:

claudeDesktopConfig({ apiKey: '…', baseUrl: 'https://kodori.staging.acme.com' });

TypeScript

The SDK is TypeScript-first. Types ship with the package; no @types/* install required. ESM-only — use import not require.

License

MIT.