sea-dev 1.0.0

package/apps/mcp/README.md

@@ -0,0 +1,171 @@
+# Sea.dev MCP Server
+
+A Model Context Protocol (MCP) server that provides tools for interacting with the sea.dev API. This enables AI assistants like Claude to work with your financial document extraction deals, forms, and submissions.
+
+## Features
+
+This MCP server provides tools for:
+
+- **Deals**: Create, list, and update deals
+- **Forms**: Create, list, and retrieve form structures with groups and fields
+- **Submissions**: Create, list, and retrieve submissions with extracted data
+- **Chat**: Interact with AI assistants for forms and submissions
+- **Workflows**: List and retrieve workflows
+
+## Installation
+
+### Prerequisites
+
+- Node.js >= 22.0.0
+- pnpm >= 10.13.0
+- A sea.dev API key (get one from [sea.dev dashboard](https://sea.dev))
+
+### Setup
+
+1. Install dependencies:
+
+```bash
+pnpm install
+```
+
+2. Build the server:
+
+```bash
+pnpm build
+```
+
+## Configuration
+
+### Environment Variables
+
+- `SEA_API_KEY` (required): Your sea.dev API key
+- `SEA_API_URL` (optional): API base URL (defaults to `https://api.sea.dev`)
+
+### Claude Desktop Configuration
+
+Add the following to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "sea": {
+      "command": "node",
+      "args": ["/absolute/path/to/sea/apps/mcp-server/dist/index.js"],
+      "env": {
+        "SEA_API_KEY": "sk-sea-your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+**Important**:
+
+- Replace `/absolute/path/to/sea` with the actual absolute path to this repository
+- Replace `sk-sea-your-api-key-here` with your actual sea.dev API key
+- See `claude_desktop_config.example.json` for a template
+- Restart Claude Desktop after making configuration changes
+
+## Available Tools
+
+### Deal Management
+
+- **list_deals**: List all deals for your organization
+- **create_deal**: Create a new deal with name, refId, and hint
+- **update_deal**: Update an existing deal (partial update)
+
+### Form Management
+
+- **list_forms**: List all forms for your organization
+- **get_form**: Get a specific form with its complete structure
+- **create_form**: Create a complete form with groups and fields
+
+### Submission Management
+
+- **list_submissions**: List all submissions
+- **get_submission**: Get a specific submission by ID
+- **create_submission**: Create a new submission linking a form to a deal
+- **get_submission_data**: Get the extracted data for a submission
+- **get_submission_status**: Get the processing status of a submission
+
+### Chat Assistants
+
+- **chat_with_submission**: Ask questions about submission data
+- **get_submission_chat_history**: Retrieve chat history for a submission
+- **chat_with_form**: Modify form structure using natural language
+- **get_form_chat_history**: Retrieve chat history for a form
+
+### Workflow Management
+
+- **list_workflows**: List all workflows
+- **get_workflow**: Get a specific workflow by ID
+
+## Usage Examples
+
+Once configured in Claude Desktop, you can use natural language to interact with your sea.dev data:
+
+- "List all my deals"
+- "Create a new deal called 'Acme Corp Q1 2024'"
+- "Show me the forms in my organization"
+- "Create a Balance Sheet form with Assets and Liabilities groups"
+- "Get the extracted data from submission xyz123"
+- "What's the total revenue in this submission?"
+
+## Development
+
+### Run in development mode
+
+```bash
+pnpm dev
+```
+
+### Type checking
+
+```bash
+pnpm check
+```
+
+### Linting and formatting
+
+```bash
+pnpm fmt
+pnpm lint
+```
+
+## Architecture
+
+This MCP server acts as a bridge between Claude and the sea.dev API:
+
+1. Claude sends tool requests via the Model Context Protocol
+2. The MCP server translates these into sea.dev API calls
+3. Responses are formatted and returned to Claude
+4. Claude uses the data to help you work with financial documents
+
+## Security
+
+- The API key is stored locally in your Claude Desktop configuration
+- All API requests use HTTPS
+- The server runs locally on your machine
+
+## Troubleshooting
+
+### Server not appearing in Claude
+
+1. Check that the path in `claude_desktop_config.json` is correct
+2. Ensure the server is built (`pnpm build`)
+3. Restart Claude Desktop after configuration changes
+4. Check Claude's logs for error messages
+
+### API Key Issues
+
+- Verify your API key is valid
+- Ensure it's properly set in the environment configuration
+- Check that the key has the necessary permissions
+
+## License
+
+See the main repository LICENSE file.

package/apps/mcp/eslint.config.mjs

@@ -0,0 +1,3 @@
+import config from "@sea/lint/eslint";
+
+export default config;

package/apps/mcp/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@sea/mcp",
+  "private": true,
+  "type": "module",
+  "version": "1.0.0",
+  "description": "MCP server for sea.dev API",
+  "bin": {
+    "sea-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "dev": "dotenvx run -- tsx src/index.ts",
+    "build": "vite build",
+    "start": "node dist/index.js",
+    "fmt": "prettier --log-level warn --write .",
+    "lint": "eslint src/",
+    "check": "tsc --noEmit",
+    "ci:fmt": "prettier --check .",
+    "ci:lint": "pnpm run lint",
+    "ci:check": "pnpm run check",
+    "all": "pnpm run fmt && pnpm run lint && pnpm run check"
+  },
+  "dependencies": {
+    "@dotenvx/dotenvx": "^1.52.0",
+    "@modelcontextprotocol/sdk": "^1.0.6",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@sea/lint": "workspace:*",
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "vite": "^7.1.2"
+  },
+  "engines": {
+    "node": ">=22.0.0 <23.0.0",
+    "pnpm": ">=10.13.0 <11.0.0"
+  }
+}

package/apps/mcp/src/index.ts

@@ -0,0 +1,414 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// API configuration
+const API_BASE_URL = process.env.SEA_API_URL || "https://api.sea.dev";
+const API_KEY = process.env.SEA_API_KEY;
+
+if (!API_KEY) {
+  console.error("Error: SEA_API_KEY environment variable is required");
+  process.exit(1);
+}
+
+// Helper function to make API requests
+async function apiRequest(
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<unknown> {
+  const url = `${API_BASE_URL}${path}`;
+  const options: RequestInit = {
+    method,
+    headers: {
+      Authorization: `Bearer ${API_KEY}`,
+      "Content-Type": "application/json",
+    },
+  };
+
+  if (body) {
+    options.body = JSON.stringify(body);
+  }
+
+  const response = await fetch(url, options);
+
+  if (!response.ok) {
+    throw new Error(
+      `API request failed: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  return response.json();
+}
+
+// Create the server
+const server = new McpServer({
+  name: "sea-mcp-server",
+  version: "1.0.0",
+});
+
+// Register tools based on the OpenAPI spec
+
+// Deals
+server.registerTool(
+  "list_deals",
+  { description: "List all deals for your organization" },
+  async () => {
+    const result = await apiRequest("GET", "/v2/deals/");
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "create_deal",
+  {
+    description: "Create a new deal",
+    inputSchema: {
+      name: z.string().describe("Deal name"),
+      refId: z.string().optional().describe("External reference ID"),
+      hint: z.string().optional().describe("Additional context or notes"),
+    },
+  },
+  async ({ name, refId, hint }) => {
+    const result = await apiRequest("POST", "/v2/deals/", {
+      name,
+      refId,
+      hint,
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "update_deal",
+  {
+    description: "Update an existing deal (partial update)",
+    inputSchema: {
+      dealId: z.string().describe("Deal ID"),
+      name: z.string().optional().describe("Deal name"),
+      refId: z.string().optional().describe("External reference ID"),
+      hint: z.string().optional().describe("Additional context or notes"),
+    },
+  },
+  async ({ dealId, name, refId, hint }) => {
+    const result = await apiRequest("PATCH", `/v2/deals/${dealId}`, {
+      name,
+      refId,
+      hint,
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+// Forms
+server.registerTool(
+  "list_forms",
+  { description: "List all forms for your organization" },
+  async () => {
+    const result = await apiRequest("GET", "/v2/forms/");
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "get_form",
+  {
+    description:
+      "Get a specific form by ID with its complete structure including groups and fields",
+    inputSchema: {
+      formId: z.string().describe("Form ID"),
+    },
+  },
+  async ({ formId }) => {
+    const result = await apiRequest("GET", `/v2/forms/${formId}`);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "create_form",
+  {
+    description: "Create a complete form with groups and fields",
+    inputSchema: {
+      workflowId: z.string().describe("Workflow ID"),
+      name: z.string().describe("Form name"),
+      hint: z.string().optional().describe("Form hint/description"),
+      groups: z
+        .array(
+          z.object({
+            name: z.string().describe("Group name"),
+            multi: z.boolean().optional().describe("Allow multiple instances"),
+            hint: z.string().optional().describe("Group hint"),
+            fields: z.array(
+              z.object({
+                name: z.string().describe("Field name"),
+                type: z
+                  .enum([
+                    "string",
+                    "string-long",
+                    "number",
+                    "boolean",
+                    "date",
+                    "email",
+                    "money",
+                    "url",
+                  ])
+                  .optional()
+                  .describe("Field type"),
+                hint: z.string().optional().describe("Field hint"),
+              }),
+            ),
+          }),
+        )
+        .describe("Form groups"),
+    },
+  },
+  async (args) => {
+    const result = await apiRequest("POST", "/v2/forms/create", args);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+// Submissions
+server.registerTool(
+  "list_submissions",
+  { description: "List all submissions for your organization" },
+  async () => {
+    const result = await apiRequest("GET", "/v2/submissions/");
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "get_submission",
+  {
+    description: "Get a specific submission by ID",
+    inputSchema: {
+      submissionId: z.string().describe("Submission ID"),
+    },
+  },
+  async ({ submissionId }) => {
+    const result = await apiRequest("GET", `/v2/submissions/${submissionId}`);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "create_submission",
+  {
+    description: "Create a new submission",
+    inputSchema: {
+      formId: z.string().describe("Form ID"),
+      dealId: z.string().describe("Deal ID"),
+    },
+  },
+  async ({ formId, dealId }) => {
+    const result = await apiRequest("POST", "/v2/submissions/", {
+      formId,
+      dealId,
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "get_submission_data",
+  {
+    description: "Get the extracted data for a submission",
+    inputSchema: {
+      submissionId: z.string().describe("Submission ID"),
+    },
+  },
+  async ({ submissionId }) => {
+    const result = await apiRequest(
+      "GET",
+      `/v2/submissions/${submissionId}/data`,
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "get_submission_status",
+  {
+    description: "Get the processing status of a submission",
+    inputSchema: {
+      submissionId: z.string().describe("Submission ID"),
+    },
+  },
+  async ({ submissionId }) => {
+    const result = await apiRequest(
+      "GET",
+      `/v2/submissions/${submissionId}/status`,
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+// Chat
+server.registerTool(
+  "chat_with_submission",
+  {
+    description:
+      "Chat with a submission's AI assistant to ask questions about the data",
+    inputSchema: {
+      submissionId: z.string().describe("Submission ID"),
+      message: z.string().describe("Message to send"),
+    },
+  },
+  async ({ submissionId, message }) => {
+    const result = await apiRequest(
+      "POST",
+      `/v2/chat/submission/${submissionId}/send`,
+      { message },
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "get_submission_chat_history",
+  {
+    description: "Get the chat history for a submission",
+    inputSchema: {
+      submissionId: z.string().describe("Submission ID"),
+    },
+  },
+  async ({ submissionId }) => {
+    const result = await apiRequest(
+      "GET",
+      `/v2/chat/submission/${submissionId}/history`,
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "chat_with_form",
+  {
+    description: "Chat with a form's AI assistant to modify form structure",
+    inputSchema: {
+      formId: z.string().describe("Form ID"),
+      message: z.string().describe("Message to send"),
+    },
+  },
+  async ({ formId, message }) => {
+    const result = await apiRequest("POST", `/v2/chat/form/${formId}/send`, {
+      message,
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "get_form_chat_history",
+  {
+    description: "Get the chat history for a form",
+    inputSchema: {
+      formId: z.string().describe("Form ID"),
+    },
+  },
+  async ({ formId }) => {
+    const result = await apiRequest("GET", `/v2/chat/form/${formId}/history`);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+// Workflows
+server.registerTool(
+  "list_workflows",
+  { description: "List all workflows for your organization" },
+  async () => {
+    const result = await apiRequest("GET", "/v2/workflows/");
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+server.registerTool(
+  "get_workflow",
+  {
+    description: "Get a specific workflow by ID",
+    inputSchema: {
+      workflowId: z.string().describe("Workflow ID"),
+    },
+  },
+  async ({ workflowId }) => {
+    const result = await apiRequest("GET", `/v2/workflows/${workflowId}`);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  },
+);
+
+// Extractions
+server.registerTool(
+  "upload_file_to_submission",
+  {
+    description:
+      "Upload one or more documents to a submission for extraction. Files are processed asynchronously using AI models to extract structured data. Note: File upload via MCP is not yet supported - use the REST API directly with multipart/form-data.",
+    inputSchema: {
+      submissionId: z.string().describe("Submission ID"),
+      filePath: z.string().describe("Local file path to upload"),
+      model: z
+        .enum(["general", "smart", "bank_statement", "financials"])
+        .optional()
+        .describe("Extraction model to use"),
+      userPrompt: z
+        .string()
+        .optional()
+        .describe("Optional custom extraction instructions"),
+    },
+  },
+  async ({ submissionId }) => {
+    throw new Error(
+      "File upload not supported via MCP. Use the REST API directly:\n" +
+        `POST ${API_BASE_URL}/v2/submissions/${submissionId}/extractions\n` +
+        "Content-Type: multipart/form-data\n" +
+        "Include 'files' field with file(s), optional 'model' and 'userPrompt' fields.",
+    );
+  },
+);
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Sea.dev MCP server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/apps/mcp/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noUncheckedIndexedAccess": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/apps/mcp/vite.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from "vite";
+import { resolve } from "path";
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, "src/index.ts"),
+      formats: ["es"],
+      fileName: () => "index.js",
+    },
+    rollupOptions: {
+      external: ["@modelcontextprotocol/sdk", "zod", /^node:.*/],
+      output: {
+        banner: "#!/usr/bin/env node",
+      },
+    },
+    target: "node22",
+    outDir: "dist",
+    emptyOutDir: true,
+    sourcemap: true,
+  },
+});

package/apps/posthog-proxy/index.html

@@ -0,0 +1,9 @@
+<!doctype html>
+<html>
+  <head>
+    <title>hello from sea.dev</title>
+  </head>
+  <body>
+    hello from sea.dev
+  </body>
+</html>

package/apps/workers/.prettierignore

@@ -0,0 +1,7 @@
+dist
+*.gen.ts
+*.md
+.tanstack
+.nitro
+.output
+.claude

package/apps/workers/.prettierrc.js

@@ -0,0 +1,3 @@
+import config from "@sea/lint/prettier";
+
+export default config;

package/apps/workers/dotenvx-safe.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+ENV_VARS=$(dotenvx run -- env)
+DATABASE_URL=$(echo "$ENV_VARS" | grep "DATABASE_URL=" | cut -d'=' -f2-)
+
+if [[ "$DATABASE_URL" != *"localhost"* ]]; then
+  echo "DATABASE_URL does not contain 'localhost'. Aborting."
+  exit 1
+fi
+
+exec dotenvx run -- "$@"