clearance-mcp 1.0.0

package/README.md

@@ -0,0 +1,118 @@
+# clearance-mcp
+
+> Model Context Protocol server for [Clearance](https://clearance.nauti-labs.com) — the human approval API for AI agent commerce.
+
+Stop letting agents move money you didn't approve. One API call. The human approves with one tap. Any service verifies the signed token.
+
+---
+
+## What This Is
+
+An MCP server that exposes Clearance as a set of tools Claude (and other MCP-compatible clients) can call natively. Your AI agent can:
+
+- Request human approval before spending money
+- Check approval status
+- Verify signed tokens
+- Manage API keys and usage
+
+---
+
+## Installation
+
+### Via npm (recommended)
+
+```bash
+npm install -g clearance-mcp
+```
+
+Or run directly via npx:
+
+```bash
+npx -y clearance-mcp
+```
+
+### Via GitHub (if npm not available)
+
+```bash
+npx -y github:Nauti-Labs/clearance-mcp
+```
+
+---
+
+## Configuration
+
+### Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "clearance": {
+      "command": "npx",
+      "args": ["-y", "clearance-mcp"],
+      "env": {
+        "CLEARANCE_API_KEY": "clr_live_..."
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CLEARANCE_API_KEY` | ✅ | Your Clearance API key (get free at clearance.nauti-labs.com) |
+| `CLEARANCE_BASE_URL` | ❌ | Override API base URL (default: https://clearance.nauti-labs.com) |
+
+---
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `clearances_create` | Create a new human approval request |
+| `clearances_get` | Get a single clearance by ID |
+| `clearances_list` | List all clearances with optional filtering |
+| `clearances_approve` | Approve a pending clearance |
+| `clearances_deny` | Deny a pending clearance |
+| `verify_token` | Verify a signed approval token |
+| `keys_create` | Create a new API key |
+| `usage_get` | Check current usage and limits |
+
+---
+
+## Example Usage
+
+In Claude, after the MCP server is connected:
+
+> **You:** "I want to book a $500 flight. Can you ask for approval first?"
+>
+> **Claude:** *calls `clearances_create` with title="Book flight to Austin", budget_amount=500*
+>
+> **Claude:** "I've created an approval request. Here's the link: [Approve](https://clearance.nauti-labs.com/approve/clr_abc123). Once you approve, I'll proceed with the booking."
+
+---
+
+## Pricing
+
+Clearance pricing:
+
+- **Starter** — Free, 50 clearances/month
+- **Pro** — $19/mo, 1,000 clearances/month
+- **Scale** — $49/mo, 10,000 clearances/month
+
+Get your free key at [clearance.nauti-labs.com](https://clearance.nauti-labs.com).
+
+---
+
+## Links
+
+- **Product:** [clearance.nauti-labs.com](https://clearance.nauti-labs.com)
+- **Company:** [nauti-labs.com](https://nauti-labs.com)
+- **API Docs:** [clearance.nauti-labs.com/v1/docs](https://clearance.nauti-labs.com/v1/docs)
+
+---
+
+Built by [Nauti-Labs LLC](https://nauti-labs.com) · Mont Belvieu, TX

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import type { ClearanceRequest, ClearanceResponse, ClearanceListResponse, VerifyTokenResponse, KeyCreateRequest, KeyCreateResponse, UsageResponse } from "./types.js";
+export declare class ClearanceClient {
+    private baseUrl;
+    private apiKey;
+    private timeoutMs;
+    constructor(apiKey: string, baseUrl?: string, timeoutMs?: number);
+    private request;
+    createClearance(data: ClearanceRequest): Promise<ClearanceResponse>;
+    getClearance(id: string): Promise<ClearanceResponse>;
+    listClearances(params?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ClearanceListResponse>;
+    approveClearance(id: string): Promise<ClearanceResponse>;
+    denyClearance(id: string, reason?: string): Promise<ClearanceResponse>;
+    verifyToken(token: string): Promise<VerifyTokenResponse>;
+    createKey(data: KeyCreateRequest): Promise<KeyCreateResponse>;
+    getUsage(): Promise<UsageResponse>;
+}

package/dist/client.js

@@ -0,0 +1,68 @@
+export class ClearanceClient {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    constructor(apiKey, baseUrl = "https://clearance.nauti-labs.com", timeoutMs = 10000) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.timeoutMs = timeoutMs;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method,
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-API-Key": this.apiKey,
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            if (!response.ok) {
+                const text = await response.text();
+                throw new Error(`Clearance API error ${response.status}: ${text || response.statusText}`);
+            }
+            return (await response.json());
+        }
+        catch (err) {
+            clearTimeout(timeout);
+            throw err;
+        }
+    }
+    async createClearance(data) {
+        return this.request("POST", "/v1/clearances", data);
+    }
+    async getClearance(id) {
+        return this.request("GET", `/v1/clearances/${encodeURIComponent(id)}`);
+    }
+    async listClearances(params) {
+        const query = new URLSearchParams();
+        if (params?.status)
+            query.set("status", params.status);
+        if (params?.limit !== undefined)
+            query.set("limit", String(params.limit));
+        if (params?.offset !== undefined)
+            query.set("offset", String(params.offset));
+        const qs = query.toString();
+        return this.request("GET", `/v1/clearances${qs ? "?" + qs : ""}`);
+    }
+    async approveClearance(id) {
+        return this.request("POST", `/v1/clearances/${encodeURIComponent(id)}/approve`);
+    }
+    async denyClearance(id, reason) {
+        return this.request("POST", `/v1/clearances/${encodeURIComponent(id)}/deny`, { reason });
+    }
+    async verifyToken(token) {
+        return this.request("GET", `/v1/verify/${encodeURIComponent(token)}`);
+    }
+    async createKey(data) {
+        return this.request("POST", "/v1/keys", data);
+    }
+    async getUsage() {
+        return this.request("GET", "/v1/usage");
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ClearanceClient } from "./client.js";
+const API_KEY = process.env.CLEARANCE_API_KEY;
+const BASE_URL = process.env.CLEARANCE_BASE_URL || "https://clearance.nauti-labs.com";
+if (!API_KEY) {
+    console.error("CLEARANCE_API_KEY environment variable is required");
+    process.exit(1);
+}
+const client = new ClearanceClient(API_KEY, BASE_URL);
+const TOOLS = [
+    {
+        name: "clearances_create",
+        description: "Create a new human approval request. The agent describes what it wants to do, the human gets a URL to approve or deny with one tap. Returns the clearance with an approve_url and deny_url.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: {
+                    type: "string",
+                    description: "Human-readable description of what the agent wants to do",
+                },
+                scope: {
+                    type: "string",
+                    description: "Machine-readable scope tag (e.g. 'purchase:flight', 'transfer:usdc')",
+                },
+                budget_amount: {
+                    type: "number",
+                    description: "Maximum amount the agent is requesting to spend",
+                },
+                budget_currency: {
+                    type: "string",
+                    description: "Currency code (default: USD)",
+                    default: "USD",
+                },
+                metadata: {
+                    type: "object",
+                    description: "Arbitrary key-value data attached to the clearance",
+                },
+                webhook_url: {
+                    type: "string",
+                    description: "URL to POST when the clearance is approved or denied",
+                },
+            },
+            required: ["title"],
+        },
+    },
+    {
+        name: "clearances_get",
+        description: "Get a single clearance by ID. Returns the full status, token, approval URL, and metadata.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Clearance ID (e.g. clr_a1b2c3d4)",
+                },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "clearances_list",
+        description: "List all clearances with optional filtering by status, pagination.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                status: {
+                    type: "string",
+                    description: "Filter by status: pending, approved, denied, revoked",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max items per page (default: 20)",
+                    default: 20,
+                },
+                offset: {
+                    type: "number",
+                    description: "Pagination offset (default: 0)",
+                    default: 0,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "clearances_approve",
+        description: "Approve a pending clearance by ID. This is typically done by the human, not the agent — but the API allows it for automated flows. Returns the updated clearance with a signed token.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Clearance ID to approve",
+                },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "clearances_deny",
+        description: "Deny a pending clearance by ID. Optionally provide a reason. Returns the updated clearance.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Clearance ID to deny",
+                },
+                reason: {
+                    type: "string",
+                    description: "Optional reason for denial",
+                },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "verify_token",
+        description: "Verify a signed clearance token. Any service can verify a token without authentication — this is how you prove a clearance was approved.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                token: {
+                    type: "string",
+                    description: "The JWT token returned when a clearance was approved",
+                },
+            },
+            required: ["token"],
+        },
+    },
+    {
+        name: "keys_create",
+        description: "Create a new Clearance API key. You can request a specific tier (starter, pro, scale). Returns the new key and its limits.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tier: {
+                    type: "string",
+                    description: "Tier: starter (free), pro ($19/mo), scale ($49/mo)",
+                    default: "starter",
+                },
+                email: {
+                    type: "string",
+                    description: "Optional email for key notifications",
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "usage_get",
+        description: "Get current usage and limits for this API key. Shows tier, monthly quota, used count, remaining count, and reset date.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+];
+const server = new Server({
+    name: "clearance-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        switch (name) {
+            case "clearances_create": {
+                const { title, scope, budget_amount, budget_currency, metadata, webhook_url } = args;
+                result = await client.createClearance({
+                    title: String(title),
+                    scope: scope ? String(scope) : undefined,
+                    budget_amount: typeof budget_amount === "number" ? budget_amount : undefined,
+                    budget_currency: budget_currency ? String(budget_currency) : undefined,
+                    metadata: typeof metadata === "object" && metadata !== null ? metadata : undefined,
+                    webhook_url: webhook_url ? String(webhook_url) : undefined,
+                });
+                break;
+            }
+            case "clearances_get": {
+                const { id } = args;
+                result = await client.getClearance(id);
+                break;
+            }
+            case "clearances_list": {
+                const { status, limit, offset } = args;
+                result = await client.listClearances({
+                    status: status ? String(status) : undefined,
+                    limit: typeof limit === "number" ? limit : undefined,
+                    offset: typeof offset === "number" ? offset : undefined,
+                });
+                break;
+            }
+            case "clearances_approve": {
+                const { id } = args;
+                result = await client.approveClearance(id);
+                break;
+            }
+            case "clearances_deny": {
+                const { id, reason } = args;
+                result = await client.denyClearance(id, reason);
+                break;
+            }
+            case "verify_token": {
+                const { token } = args;
+                result = await client.verifyToken(token);
+                break;
+            }
+            case "keys_create": {
+                const { tier, email } = args;
+                result = await client.createKey({
+                    tier: tier ? String(tier) : undefined,
+                    email: email ? String(email) : undefined,
+                });
+                break;
+            }
+            case "usage_get": {
+                result = await client.getUsage();
+                break;
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Clearance MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/types.d.ts

@@ -0,0 +1,67 @@
+export interface ClearanceRequest {
+    title: string;
+    scope?: string;
+    budget_amount?: number;
+    budget_currency?: string;
+    metadata?: Record<string, unknown>;
+    webhook_url?: string;
+}
+export interface ClearanceResponse {
+    id: string;
+    title: string;
+    scope: string | null;
+    budget_amount: number | null;
+    budget_currency: string | null;
+    status: "pending" | "approved" | "denied" | "revoked";
+    approve_url: string;
+    deny_url: string;
+    token: string | null;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+    approved_at: string | null;
+    denied_at: string | null;
+    denied_reason: string | null;
+}
+export interface ClearanceListResponse {
+    items: ClearanceResponse[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface VerifyTokenResponse {
+    valid: boolean;
+    clearance_id: string;
+    status: string;
+    created_at: string;
+    approved_at: string | null;
+    metadata: Record<string, unknown> | null;
+}
+export interface KeyCreateRequest {
+    tier?: string;
+    email?: string;
+}
+export interface KeyCreateResponse {
+    key: string;
+    tier: string;
+    clearances_per_month: number;
+    created_at: string;
+}
+export interface UsageResponse {
+    tier: string;
+    clearances_per_month: number;
+    used_this_month: number;
+    remaining_this_month: number;
+    reset_date: string;
+}
+export interface ClearanceApproveRequest {
+    id: string;
+}
+export interface ClearanceDenyRequest {
+    id: string;
+    reason?: string;
+}
+export interface ClearanceListRequest {
+    status?: string;
+    limit?: number;
+    offset?: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Clearance API types
+export {};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "clearance-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Clearance — human approval API for AI agent commerce",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "clearance-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "clearance",
+    "approval",
+    "agent",
+    "ai",
+    "payments"
+  ],
+  "author": "Nauti-Labs LLC",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5.9.3"
+  }
+}

package/src/client.ts

@@ -0,0 +1,90 @@
+import type { ClearanceRequest, ClearanceResponse, ClearanceListResponse, VerifyTokenResponse, KeyCreateRequest, KeyCreateResponse, UsageResponse } from "./types.js";
+
+export class ClearanceClient {
+  private baseUrl: string;
+  private apiKey: string;
+  private timeoutMs: number;
+
+  constructor(apiKey: string, baseUrl = "https://clearance.nauti-labs.com", timeoutMs = 10000) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.timeoutMs = timeoutMs;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.apiKey,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeout);
+
+      if (!response.ok) {
+        const text = await response.text();
+        throw new Error(
+          `Clearance API error ${response.status}: ${text || response.statusText}`
+        );
+      }
+
+      return (await response.json()) as T;
+    } catch (err) {
+      clearTimeout(timeout);
+      throw err;
+    }
+  }
+
+  async createClearance(data: ClearanceRequest): Promise<ClearanceResponse> {
+    return this.request<ClearanceResponse>("POST", "/v1/clearances", data);
+  }
+
+  async getClearance(id: string): Promise<ClearanceResponse> {
+    return this.request<ClearanceResponse>("GET", `/v1/clearances/${encodeURIComponent(id)}`);
+  }
+
+  async listClearances(params?: {
+    status?: string;
+    limit?: number;
+    offset?: number;
+  }): Promise<ClearanceListResponse> {
+    const query = new URLSearchParams();
+    if (params?.status) query.set("status", params.status);
+    if (params?.limit !== undefined) query.set("limit", String(params.limit));
+    if (params?.offset !== undefined) query.set("offset", String(params.offset));
+    const qs = query.toString();
+    return this.request<ClearanceListResponse>("GET", `/v1/clearances${qs ? "?" + qs : ""}`);
+  }
+
+  async approveClearance(id: string): Promise<ClearanceResponse> {
+    return this.request<ClearanceResponse>("POST", `/v1/clearances/${encodeURIComponent(id)}/approve`);
+  }
+
+  async denyClearance(id: string, reason?: string): Promise<ClearanceResponse> {
+    return this.request<ClearanceResponse>("POST", `/v1/clearances/${encodeURIComponent(id)}/deny`, { reason });
+  }
+
+  async verifyToken(token: string): Promise<VerifyTokenResponse> {
+    return this.request<VerifyTokenResponse>("GET", `/v1/verify/${encodeURIComponent(token)}`);
+  }
+
+  async createKey(data: KeyCreateRequest): Promise<KeyCreateResponse> {
+    return this.request<KeyCreateResponse>("POST", "/v1/keys", data);
+  }
+
+  async getUsage(): Promise<UsageResponse> {
+    return this.request<UsageResponse>("GET", "/v1/usage");
+  }
+}

package/src/index.ts

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+import { ClearanceClient } from "./client.js";
+
+const API_KEY = process.env.CLEARANCE_API_KEY;
+const BASE_URL = process.env.CLEARANCE_BASE_URL || "https://clearance.nauti-labs.com";
+
+if (!API_KEY) {
+  console.error("CLEARANCE_API_KEY environment variable is required");
+  process.exit(1);
+}
+
+const client = new ClearanceClient(API_KEY, BASE_URL);
+
+const TOOLS: Tool[] = [
+  {
+    name: "clearances_create",
+    description: "Create a new human approval request. The agent describes what it wants to do, the human gets a URL to approve or deny with one tap. Returns the clearance with an approve_url and deny_url.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description: "Human-readable description of what the agent wants to do",
+        },
+        scope: {
+          type: "string",
+          description: "Machine-readable scope tag (e.g. 'purchase:flight', 'transfer:usdc')",
+        },
+        budget_amount: {
+          type: "number",
+          description: "Maximum amount the agent is requesting to spend",
+        },
+        budget_currency: {
+          type: "string",
+          description: "Currency code (default: USD)",
+          default: "USD",
+        },
+        metadata: {
+          type: "object",
+          description: "Arbitrary key-value data attached to the clearance",
+        },
+        webhook_url: {
+          type: "string",
+          description: "URL to POST when the clearance is approved or denied",
+        },
+      },
+      required: ["title"],
+    },
+  },
+  {
+    name: "clearances_get",
+    description: "Get a single clearance by ID. Returns the full status, token, approval URL, and metadata.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Clearance ID (e.g. clr_a1b2c3d4)",
+        },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "clearances_list",
+    description: "List all clearances with optional filtering by status, pagination.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          description: "Filter by status: pending, approved, denied, revoked",
+        },
+        limit: {
+          type: "number",
+          description: "Max items per page (default: 20)",
+          default: 20,
+        },
+        offset: {
+          type: "number",
+          description: "Pagination offset (default: 0)",
+          default: 0,
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "clearances_approve",
+    description: "Approve a pending clearance by ID. This is typically done by the human, not the agent — but the API allows it for automated flows. Returns the updated clearance with a signed token.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Clearance ID to approve",
+        },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "clearances_deny",
+    description: "Deny a pending clearance by ID. Optionally provide a reason. Returns the updated clearance.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Clearance ID to deny",
+        },
+        reason: {
+          type: "string",
+          description: "Optional reason for denial",
+        },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "verify_token",
+    description: "Verify a signed clearance token. Any service can verify a token without authentication — this is how you prove a clearance was approved.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        token: {
+          type: "string",
+          description: "The JWT token returned when a clearance was approved",
+        },
+      },
+      required: ["token"],
+    },
+  },
+  {
+    name: "keys_create",
+    description: "Create a new Clearance API key. You can request a specific tier (starter, pro, scale). Returns the new key and its limits.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tier: {
+          type: "string",
+          description: "Tier: starter (free), pro ($19/mo), scale ($49/mo)",
+          default: "starter",
+        },
+        email: {
+          type: "string",
+          description: "Optional email for key notifications",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "usage_get",
+    description: "Get current usage and limits for this API key. Shows tier, monthly quota, used count, remaining count, and reset date.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+];
+
+const server = new Server(
+  {
+    name: "clearance-mcp",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: TOOLS };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    let result: unknown;
+
+    switch (name) {
+      case "clearances_create": {
+        const { title, scope, budget_amount, budget_currency, metadata, webhook_url } = args as Record<string, unknown>;
+        result = await client.createClearance({
+          title: String(title),
+          scope: scope ? String(scope) : undefined,
+          budget_amount: typeof budget_amount === "number" ? budget_amount : undefined,
+          budget_currency: budget_currency ? String(budget_currency) : undefined,
+          metadata: typeof metadata === "object" && metadata !== null ? (metadata as Record<string, unknown>) : undefined,
+          webhook_url: webhook_url ? String(webhook_url) : undefined,
+        });
+        break;
+      }
+      case "clearances_get": {
+        const { id } = args as Record<string, string>;
+        result = await client.getClearance(id);
+        break;
+      }
+      case "clearances_list": {
+        const { status, limit, offset } = args as Record<string, unknown>;
+        result = await client.listClearances({
+          status: status ? String(status) : undefined,
+          limit: typeof limit === "number" ? limit : undefined,
+          offset: typeof offset === "number" ? offset : undefined,
+        });
+        break;
+      }
+      case "clearances_approve": {
+        const { id } = args as Record<string, string>;
+        result = await client.approveClearance(id);
+        break;
+      }
+      case "clearances_deny": {
+        const { id, reason } = args as Record<string, string>;
+        result = await client.denyClearance(id, reason);
+        break;
+      }
+      case "verify_token": {
+        const { token } = args as Record<string, string>;
+        result = await client.verifyToken(token);
+        break;
+      }
+      case "keys_create": {
+        const { tier, email } = args as Record<string, unknown>;
+        result = await client.createKey({
+          tier: tier ? String(tier) : undefined,
+          email: email ? String(email) : undefined,
+        });
+        break;
+      }
+      case "usage_get": {
+        result = await client.getUsage();
+        break;
+      }
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: ${message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Clearance MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/src/types.ts

@@ -0,0 +1,78 @@
+// Clearance API types
+
+export interface ClearanceRequest {
+  title: string;
+  scope?: string;
+  budget_amount?: number;
+  budget_currency?: string;
+  metadata?: Record<string, unknown>;
+  webhook_url?: string;
+}
+
+export interface ClearanceResponse {
+  id: string;
+  title: string;
+  scope: string | null;
+  budget_amount: number | null;
+  budget_currency: string | null;
+  status: "pending" | "approved" | "denied" | "revoked";
+  approve_url: string;
+  deny_url: string;
+  token: string | null;
+  metadata: Record<string, unknown> | null;
+  created_at: string;
+  approved_at: string | null;
+  denied_at: string | null;
+  denied_reason: string | null;
+}
+
+export interface ClearanceListResponse {
+  items: ClearanceResponse[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+export interface VerifyTokenResponse {
+  valid: boolean;
+  clearance_id: string;
+  status: string;
+  created_at: string;
+  approved_at: string | null;
+  metadata: Record<string, unknown> | null;
+}
+
+export interface KeyCreateRequest {
+  tier?: string;
+  email?: string;
+}
+
+export interface KeyCreateResponse {
+  key: string;
+  tier: string;
+  clearances_per_month: number;
+  created_at: string;
+}
+
+export interface UsageResponse {
+  tier: string;
+  clearances_per_month: number;
+  used_this_month: number;
+  remaining_this_month: number;
+  reset_date: string;
+}
+
+export interface ClearanceApproveRequest {
+  id: string;
+}
+
+export interface ClearanceDenyRequest {
+  id: string;
+  reason?: string;
+}
+
+export interface ClearanceListRequest {
+  status?: string;
+  limit?: number;
+  offset?: number;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}