@setluca/mcp 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# Luca MCP
+
+TypeScript MCP server for the Luca public API.
+
+Luca MCP lets MCP clients call Luca's API-key-safe public API operations as
+tools. It is intentionally narrow: it does not access Luca's database, browser
+sessions, private webhook ingress, or `/internal/*` routes.
+
+## Status
+
+- Transports: stdio (this npm package) and remote Streamable HTTP
+  (`src/worker.ts`, deployed as the `setluca-mcp` Cloudflare Worker at
+  `https://mcp.setluca.com/mcp`)
+- Runtime: Bun (dev) — the built `dist/index.js` has no Bun-only APIs
+- MCP SDK: `@modelcontextprotocol/sdk`
+- Internal architecture: TypeScript, Effect services, Zod schemas
+- Public API source of truth: `apps/api/openapi.json` (the checked-in
+  snapshot; `https://api.setluca.com/openapi.json` is the deployed copy)
+
+## Remote connection (hosted MCP clients)
+
+Hosted clients (Claude connectors, ChatGPT) connect to
+`https://mcp.setluca.com/mcp` with OAuth 2.1 — no API key pasting:
+
+1. The client discovers auth via
+   `https://mcp.setluca.com/.well-known/oauth-protected-resource/mcp`
+   (RFC 9728), which points at the Luca authorization server
+   (`https://api.setluca.com/api/auth`).
+2. It registers dynamically, then sends the coach through sign-in and a
+   scope-narrowing consent screen. Scopes: `luca:read` (baseline),
+   `luca:draft`, `luca:queue_ops`, `luca:full`, `luca:full_content`, plus
+   `offline_access` for refresh tokens. Defaults are read + draft.
+3. Coaches manage and revoke connections in Luca Settings → Connected agents.
+
+Self-hosted/scripted clients can instead present a developer API key as the
+bearer token on the same endpoint. Design and security model:
+`docs/specs/mcp-oauth-authorization-server.md` (repo root).
+
+## Quickstart
+
+> Not yet published to npm. The `npx` commands below work once the package is
+> released — see [docs/release.md](./docs/release.md) for the remaining steps.
+> Until then, build from source (further down).
+
+Once published, add Luca to any MCP client (Claude Desktop, Cursor) with a
+developer API key:
+
+```json
+{
+  "mcpServers": {
+    "luca": {
+      "command": "npx",
+      "args": ["-y", "@setluca/mcp"],
+      "env": {
+        "LUCA_API_KEY": "luca_..."
+      }
+    }
+  }
+}
+```
+
+Get a `LUCA_API_KEY` from Luca settings → developer API keys. The server needs
+only that key; it lists tools without one and returns an actionable error on the
+first tool call if it is missing.
+
+### From source (before the npm release)
+
+From the repo root:
+
+```bash
+bun install
+bun --cwd apps/mcp run build
+LUCA_API_KEY="luca_..." node apps/mcp/dist/index.js
+```
+
+MCP client configuration against the built file:
+
+```json
+{
+  "mcpServers": {
+    "luca": {
+      "command": "node",
+      "args": ["/absolute/path/to/luca/apps/mcp/dist/index.js"],
+      "env": {
+        "LUCA_API_KEY": "luca_..."
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+Required:
+
+```bash
+export LUCA_API_KEY="luca_..."
+```
+
+Optional:
+
+```bash
+export LUCA_API_BASE_URL="https://api.setluca.com"
+export LUCA_AUTH_HEADER="x-api-key" # or "authorization"
+export LUCA_WORKSPACE_ID="00000000-0000-0000-0000-000000000000"
+export LUCA_WORKSPACE_SLUG="my-workspace"
+```
+
+Every tool also accepts `workspaceId` and `workspaceSlug`, which override the
+environment for that call.
+
+## Capabilities
+
+- 67 Luca public API tools, each carrying MCP annotations (read-only /
+  destructive / idempotent hints)
+- Resources: `luca://operations` (the tool manifest), `luca://lead/{leadId}`,
+  `luca://thread/{conversationId}`, and `luca://queue/today` — attach a lead,
+  thread, or the review queue as context without a tool round-trip
+- Prompts: `luca-api-planner`, plus slash-command workflows
+  `luca-morning-report`, `luca-triage-queue`, and `luca-draft-reply`
+
+Mutating tools include `idempotencyKey`. Provide a stable key when retrying the
+same user intent; otherwise the server generates a unique key per call. Reads
+that return lead-authored text are framed as untrusted content (see
+[docs/security.md](./docs/security.md)).
+
+## Documentation
+
+- [Architecture](./docs/architecture.md)
+- [Client Setup](./docs/client-setup.md)
+- [Configuration](./docs/configuration.md)
+- [Development](./docs/development.md)
+- [Examples](./docs/examples.md)
+- [Integration Testing](./docs/integration-testing.md)
+- [MCP Inspector](./docs/inspector.md)
+- [Maintenance](./docs/maintenance.md)
+- [Security Boundary](./docs/security.md)
+- [Tool Reference](./docs/tools.md)
+
+## Development
+
+From `apps/mcp` (or `bun --filter @setluca/mcp <script>` from the root):
+
+```bash
+bun run docs:check
+bun run verify
+```
+
+`bun run verify` checks generated docs, OpenAPI input drift, the operation
+manifest against `apps/api/openapi.json`, TypeScript, tests, build output, and
+stdio startup. Lint, knip, and fallow run at the monorepo root.
+
+## API Docs
+
+- Luca API docs: https://api.setluca.com/docs
+- Luca OpenAPI JSON: https://api.setluca.com/openapi.json

package/dist/config.js

@@ -0,0 +1,47 @@
+import { Context, Effect, Layer } from "effect";
+import { LucaConfigError } from "./errors.js";
+const TRAILING_SLASHES = /\/+$/;
+export const LucaConfig = Context.GenericTag("@luca/mcp/LucaConfig");
+function nonEmpty(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function normalizeBaseUrl(value) {
+    const raw = nonEmpty(value) ?? "https://api.setluca.com";
+    return raw.replace(TRAILING_SLASHES, "");
+}
+function parseAuthHeader(value) {
+    const normalized = nonEmpty(value)?.toLowerCase();
+    if (!normalized || normalized === "x-api-key") {
+        return "x-api-key";
+    }
+    if (normalized === "authorization" || normalized === "bearer") {
+        return "authorization";
+    }
+    throw new LucaConfigError({
+        message: "LUCA_AUTH_HEADER must be x-api-key or authorization",
+    });
+}
+export function loadConfig(env = process.env) {
+    const apiKey = nonEmpty(env.LUCA_API_KEY) ?? nonEmpty(env.LUCA_API_TOKEN);
+    if (!apiKey) {
+        throw new LucaConfigError({
+            message: "Set LUCA_API_KEY to a Luca developer API key.",
+        });
+    }
+    const workspaceId = nonEmpty(env.LUCA_WORKSPACE_ID);
+    const workspaceSlug = nonEmpty(env.LUCA_WORKSPACE_SLUG);
+    return {
+        apiBaseUrl: normalizeBaseUrl(env.LUCA_API_BASE_URL),
+        apiKey,
+        authHeader: parseAuthHeader(env.LUCA_AUTH_HEADER),
+        ...(workspaceId ? { workspaceId } : {}),
+        ...(workspaceSlug ? { workspaceSlug } : {}),
+    };
+}
+export const LucaConfigLive = Layer.effect(LucaConfig, Effect.try({
+    try: () => loadConfig(),
+    catch: (cause) => cause instanceof LucaConfigError
+        ? cause
+        : new LucaConfigError({ message: String(cause) }),
+}));

package/dist/errors.js

@@ -0,0 +1,25 @@
+import { Data } from "effect";
+export class LucaConfigError extends Data.TaggedError("LucaConfigError") {
+}
+export class LucaNetworkError extends Data.TaggedError("LucaNetworkError") {
+}
+export class LucaDecodeError extends Data.TaggedError("LucaDecodeError") {
+}
+export class LucaHttpError extends Data.TaggedError("LucaHttpError") {
+}
+export function formatError(error) {
+    if (error instanceof LucaConfigError) {
+        return error.message;
+    }
+    if (error instanceof LucaNetworkError) {
+        return error.message;
+    }
+    if (error instanceof LucaDecodeError) {
+        return `${error.message}: ${error.body.slice(0, 500)}`;
+    }
+    if (error instanceof LucaHttpError) {
+        const request = error.requestId ? ` requestId=${error.requestId}` : "";
+        return `Luca API returned ${error.status} ${error.statusText}${request}: ${JSON.stringify(error.body)}`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}