formbro-mcp-server 1.0.0 → 1.0.2

package/README.md

@@ -2,69 +2,110 @@
 
 [![npm version](https://badge.fury.io/js/formbro-mcp-server.svg)](https://www.npmjs.com/package/formbro-mcp-server)
 
-MCP server for FormBro immigration management system - provides access to applicants, applications, and employers data through the Model Context Protocol.
+MCP server for FormBro Canadian immigration application automation. It provides agent access to FormBro applications, applicants, employers, validation, export, and controlled write workflows through the Model Context Protocol.
 
 ## Features
 
-- 🔍 **Smart Find Tool** - Search across applicants, applications, and employers with intelligent name matching
-- 📋 **List Operations** - Paginated listing with search and filtering
-- 📄 **Detail Views** - Comprehensive entity information retrieval
-- 🔐 **Secure Authentication** - Token-based API authentication
-- 🌐 **Dual Transport** - Supports both stdio (local) and HTTP (remote) modes
-- 📡 **SSE Support** - Server-Sent Events for streaming responses
+- **Hosted MCP** - Use `https://mcp.formbro.ca/mcp` from Claude Code, Codex, Cursor, and other MCP clients.
+- **Local stdio MCP** - Use `npx -y formbro-mcp-server` for Claude Desktop and offline debugging.
+- **Toolset gating** - Public default is `system,read,validate`; write/export/audit tools require explicit opt-in.
+- **Secure authentication** - Token-based FormBro API authentication with per-request bearer tokens for hosted HTTP.
+- **Dual transport** - Supports stdio (local) and Streamable HTTP (hosted/self-hosted) modes.
+
+## Hosted MCP Quick Start
+
+```bash
+claude mcp add --transport http formbro \
+  "https://mcp.formbro.ca/mcp?toolsets=system,read,validate" \
+  --header "Authorization: Bearer fb_your_token_here"
+```
+
+For Codex:
+
+```bash
+export FORMBRO_API_TOKEN=fb_your_token_here
+codex mcp add formbro \
+  --url "https://mcp.formbro.ca/mcp?toolsets=system,read,validate" \
+  --bearer-token-env-var FORMBRO_API_TOKEN
+```
+
+Use local stdio only when your client requires a local MCP process or you need offline debugging.
 
 ## Installation
 
+### Option 1: Using npx
+
+No installation needed - run directly:
+
 ```bash
-# Using npx (recommended)
-npx formbro-mcp-server
+npx -y formbro-mcp-server --toolsets=system,read,validate
+```
+
+### Option 2: Global Installation
 
-# Or install globally
+```bash
 npm install -g formbro-mcp-server
 ```
 
-## Usage
+### Option 3: Local Installation
 
-### Quick Start (stdio mode)
+```bash
+npm install formbro-mcp-server
+```
+
+## Quick Start
+
+### Get Your API Token
+
+1. Log in to FormBro
+2. Navigate to Settings > API Tokens
+3. Generate a new token (starts with `fb_`)
+
+### Run the Server
+
+#### stdio mode (for Claude Desktop)
 
 ```bash
-FORMBRO_API_URL=https://api.formbro.com \
-FORMBRO_API_TOKEN=your-token \
-formbro-mcp-server
+FORMBRO_API_URL=https://backend.formbro.ca \
+FORMBRO_API_TOKEN=fb_your_token_here \
+formbro-mcp-server --toolsets=system,read,validate
 ```
 
-### HTTP Server Mode
+#### HTTP mode (for remote access / Claude Code HTTP)
 
 ```bash
-FORMBRO_API_URL=https://api.formbro.com \
+FORMBRO_API_URL=https://backend.formbro.ca \
 TRANSPORT=http \
 PORT=3000 \
-formbro-mcp-server
+formbro-mcp-server --toolsets=system,read,validate
 ```
 
+**Note:** In HTTP mode, the token is provided per-request via the `Authorization` header, not in the environment.
+
 ## Configuration
 
 ### Environment Variables
 
-| Variable | Required | Description | Default |
-|----------|----------|-------------|---------|
-| `FORMBRO_API_URL` | Yes | Base URL of FormBro API | - |
-| `FORMBRO_API_TOKEN` | Yes (stdio) | API token for authentication | - |
-| `TRANSPORT` | No | Transport mode: `stdio` or `http` | `stdio` |
-| `PORT` | No | HTTP server port (http mode only) | `3000` |
+| Variable | Required | Mode | Description | Default |
+|----------|----------|------|-------------|---------|
+| `FORMBRO_API_URL` | ✅ Yes | Both | Base URL of FormBro API | - |
+| `FORMBRO_API_TOKEN` | ✅ Yes | stdio only | API token for authentication | - |
+| `TRANSPORT` | No | Both | Transport mode: `stdio` or `http` | `stdio` |
+| `PORT` or `MCP_PORT` | No | HTTP only | HTTP server port | `3000` |
 
-### Get Your API Token
+## Connecting to Claude
 
-1. Log in to FormBro
-2. Navigate to Settings > API Tokens
-3. Generate a new token
+### Claude Desktop Configuration
 
-## Connecting from Claude
+Claude Desktop uses **stdio transport** for local process communication.
 
-### Claude Desktop (stdio)
+#### Method 1: Using npx (Recommended)
 
 Add to your `claude_desktop_config.json`:
 
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
 ```json
 {
   "mcpServers": {
@@ -72,78 +113,317 @@ Add to your `claude_desktop_config.json`:
       "command": "npx",
       "args": ["-y", "formbro-mcp-server"],
       "env": {
-        "FORMBRO_API_URL": "https://api.formbro.com",
-        "FORMBRO_API_TOKEN": "your-token"
+        "FORMBRO_API_URL": "https://backend.formbro.ca",
+        "FORMBRO_API_TOKEN": "fb_your_token_here"
+      }
+    }
+  }
+}
+```
+
+#### Method 2: Using global installation
+
+```json
+{
+  "mcpServers": {
+    "formbro": {
+      "command": "formbro-mcp-server",
+      "env": {
+        "FORMBRO_API_URL": "https://backend.formbro.ca",
+        "FORMBRO_API_TOKEN": "fb_your_token_here"
       }
     }
   }
 }
 ```
 
-### Claude Code (HTTP)
+#### Method 3: Using local Node.js
+
+```json
+{
+  "mcpServers": {
+    "formbro": {
+      "command": "node",
+      "args": ["/path/to/formbro-mcp-server/dist/index.js"],
+      "env": {
+        "FORMBRO_API_URL": "https://backend.formbro.ca",
+        "FORMBRO_API_TOKEN": "fb_your_token_here"
+      }
+    }
+  }
+}
+```
+
+**Restart Claude Desktop** after updating the configuration.
+
+### Claude Code Configuration
+
+Claude Code supports both **stdio** and **HTTP** transports.
+
+#### Method 1: HTTP Transport (Recommended for Claude Code)
+
+**Step 1**: Start the HTTP server
 
 ```bash
-# Start HTTP server
-FORMBRO_API_URL=https://api.formbro.com \
+# In a terminal, run:
+FORMBRO_API_URL=https://backend.formbro.ca \
 TRANSPORT=http \
+PORT=3000 \
+formbro-mcp-server
+```
+
+Or create an `.env` file:
+
+```bash
+# .env
+FORMBRO_API_URL=https://backend.formbro.ca
+TRANSPORT=http
+MCP_PORT=3000
+```
+
+Then run:
+
+```bash
 formbro-mcp-server
+```
+
+**Step 2**: Add to Claude Code with your token
+
+```bash
+# Option A: Using Bearer token format
+claude mcp add --transport http formbro http://localhost:3000/mcp \
+  --header "Authorization: Bearer fb_your_token_here"
 
-# Add to Claude Code
+# Option B: Direct token format (also supported)
 claude mcp add --transport http formbro http://localhost:3000/mcp \
-  --header "Authorization: Bearer your-token"
+  --header "Authorization: fb_your_token_here"
+```
+
+**Verify connection:**
+
+```bash
+claude mcp list
+```
+
+#### Method 2: stdio Transport
+
+```bash
+claude mcp add --transport stdio formbro -- \
+  env FORMBRO_API_URL=https://backend.formbro.ca \
+  FORMBRO_API_TOKEN=fb_your_token_here \
+  npx -y formbro-mcp-server
+```
+
+#### Method 3: stdio with global installation
+
+```bash
+claude mcp add --transport stdio formbro -- \
+  env FORMBRO_API_URL=https://backend.formbro.ca \
+  FORMBRO_API_TOKEN=fb_your_token_here \
+  formbro-mcp-server
+```
+
+### Managing MCP Servers in Claude Code
+
+```bash
+# List all MCP servers
+claude mcp list
+
+# Remove a server
+claude mcp remove formbro
+
+# Update server configuration
+claude mcp remove formbro
+claude mcp add --transport http formbro http://localhost:3000/mcp \
+  --header "Authorization: Bearer fb_new_token"
 ```
 
 ## Available Tools
 
-### `formbro_find` (Recommended)
+### `formbro_find` ⭐ (Recommended)
 
-Smart search across all entity types with name matching and related data retrieval.
+**Smart search across all entity types with intelligent name matching.**
+
+**Why use this first?**
+- Combines search and detail fetching in one call
+- Handles "First Last" and "Last First" name order automatically
+- Returns compact JSON optimized for AI processing
+- Can include related applications in the same response
+
+**Examples:**
 
 ```typescript
-// Find applicants named "John"
-formbro_find({ query: "John" })
+// Find applicant by name
+formbro_find({ name: "Zhang Wei" })
+
+// Find with applications included
+formbro_find({ name: "John Smith", include: ["applications"] })
 
-// Find LMIA applications
-formbro_find({ query: "LMIA" })
+// Filter by program
+formbro_find({ name: "Wei", program: "tr", include: ["applications"] })
+
+// Limit results
+formbro_find({ name: "Smith", limit: 10 })
 ```
 
+**Parameters:**
+- `name` (required): Name to search for. Supports full name in any order.
+- `program` (optional): Filter by `"tr"`, `"pr"`, or `"lmia"`
+- `include` (optional): Array of `["applications"]` or `["applications", "employer"]`
+- `limit` (optional): Maximum results to return (1-20, default: 5)
+
 ### `formbro_list_applicants`
 
 List applicants with search, program filtering, and pagination.
 
+**Parameters:**
+- `limit` (optional): Maximum results to return (1-100, default: 20)
+- `offset` (optional): Number of results to skip for pagination (default: 0)
+- `search` (optional): Search query to filter by name, email, etc.
+- `program` (optional): Filter by program type (`"tr"`, `"pr"`, `"lmia"`)
+- `response_format` (optional): `"markdown"` or `"json"` (default: `"markdown"`)
+
 ### `formbro_get_applicant`
 
 Get detailed applicant information by ID.
 
+**Parameters:**
+- `id` (required): The applicant's unique identifier (MongoDB ObjectId)
+- `response_format` (optional): `"markdown"` or `"json"` (default: `"markdown"`)
+
 ### `formbro_list_applications`
 
-List applications by program type (tr/pr/lmia) with status filtering.
+List applications by program type with status filtering.
+
+**Programs:**
+- `tr` - Temporary Residence (Work permits, study permits, visitor visas)
+- `pr` - Permanent Residence (Family sponsorship, Express Entry, PNP)
+- `lmia` - Labour Market Impact Assessment (Employer applications)
+
+**Parameters:**
+- `limit` (optional): Maximum results to return (1-100, default: 20)
+- `offset` (optional): Number of results to skip for pagination (default: 0)
+- `search` (optional): Search query to filter by case name
+- `program` (optional): Filter by program type (`"tr"`, `"pr"`, `"lmia"`)
+- `status` (optional): Filter by status (`"draft"`, `"in_progress"`, `"submitted"`, `"approved"`, `"refused"`)
+- `response_format` (optional): `"markdown"` or `"json"` (default: `"markdown"`)
 
 ### `formbro_get_application`
 
 Get detailed application information by ID.
 
+**Parameters:**
+- `id` (required): The application's unique identifier (MongoDB ObjectId)
+- `response_format` (optional): `"markdown"` or `"json"` (default: `"markdown"`)
+
 ### `formbro_list_employers`
 
 List employers with search and pagination.
 
+**Parameters:**
+- `limit` (optional): Maximum results to return (1-100, default: 20)
+- `offset` (optional): Number of results to skip for pagination (default: 0)
+- `search` (optional): Search query to filter by company name, business number, etc.
+- `response_format` (optional): `"markdown"` or `"json"` (default: `"markdown"`)
+
 ### `formbro_get_employer`
 
 Get detailed employer information by ID.
 
+**Parameters:**
+- `id` (required): The employer's unique identifier (MongoDB ObjectId)
+- `response_format` (optional): `"markdown"` or `"json"` (default: `"markdown"`)
+
 ## API Response Formats
 
 All tools support two response formats:
 
-- `markdown` (default) - Human-readable formatted output
-- `json` - Machine-readable structured data
+- **`markdown`** (default) - Human-readable formatted output for Claude
+- **`json`** - Machine-readable structured data
+
+## HTTP API Endpoints
+
+When running in HTTP mode, the server exposes:
+
+### `GET /health`
+
+Health check endpoint returning server status.
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "server": "formbro-mcp-server",
+  "version": "1.0.0",
+  "apiUrl": "https://backend.formbro.ca",
+  "apiConfigured": true
+}
+```
+
+### `POST /mcp`
+
+Main MCP endpoint using Streamable HTTP transport.
+
+**Headers:**
+```
+Authorization: Bearer fb_your_token_here
+Content-Type: application/json
+```
+
+**Request Body:** MCP protocol JSON-RPC message
+
+### `GET /mcp`
+
+Returns server information and available tools.
+
+## Troubleshooting
+
+### Claude Desktop Issues
+
+**Server not connecting:**
+1. Check the config file location is correct for your OS
+2. Verify JSON syntax (use a JSON validator)
+3. Ensure the token starts with `fb_`
+4. Restart Claude Desktop after config changes
+5. Check Claude Desktop logs: `~/Library/Logs/Claude/` (macOS)
+
+**Token errors:**
+1. Generate a new token from FormBro Settings
+2. Ensure no extra spaces in the token
+3. Token should start with `fb_`
+
+### Claude Code Issues
+
+**HTTP connection failed:**
+1. Ensure the server is running (`curl http://localhost:3000/health`)
+2. Check the port is not in use by another service
+3. Verify the Authorization header format
+4. Test with `curl`:
+   ```bash
+   curl -X POST http://localhost:3000/mcp \
+     -H "Authorization: Bearer fb_your_token" \
+     -H "Content-Type: application/json" \
+     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+   ```
+
+**stdio connection failed:**
+1. Check if `npx` or `formbro-mcp-server` is in PATH
+2. Verify environment variables are set correctly
+3. Test manually:
+   ```bash
+   FORMBRO_API_URL=https://backend.formbro.ca \
+   FORMBRO_API_TOKEN=fb_your_token \
+   formbro-mcp-server
+   ```
 
 ## Development
 
+### Setup
+
 ```bash
 # Clone the repository
-git clone https://github.com/yourusername/formbro-mcp-server.git
-cd formbro-mcp-server
+git clone https://github.com/jackyzhang69/formbro.git
+cd formbro/mcp-server
 
 # Install dependencies
 pnpm install
@@ -155,6 +435,57 @@ pnpm build
 pnpm dev
 ```
 
+### Testing
+
+```bash
+# Test stdio mode
+FORMBRO_API_URL=https://backend.formbro.ca \
+FORMBRO_API_TOKEN=fb_your_token \
+pnpm start
+
+# Test HTTP mode
+FORMBRO_API_URL=https://backend.formbro.ca \
+TRANSPORT=http \
+PORT=3000 \
+pnpm start
+
+# Test health endpoint
+curl http://localhost:3000/health
+
+# Test MCP endpoint
+curl -X POST http://localhost:3000/mcp \
+  -H "Authorization: Bearer fb_your_token" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+### Project Structure
+
+```
+mcp-server/
+├── src/
+│   ├── index.ts              # Main entry point, transport setup
+│   ├── services/
+│   │   └── api-client.ts     # FormBro API client
+│   └── tools/
+│       ├── find.ts           # Smart find tool
+│       ├── applicants.ts     # Applicant tools
+│       ├── applications.ts   # Application tools
+│       └── employers.ts      # Employer tools
+├── dist/                     # Compiled JavaScript (generated)
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Security Notes
+
+- **Token Security**: Never commit API tokens to version control
+- **HTTP Mode**: Uses per-request authentication via `Authorization` header
+- **stdio Mode**: Token is passed via environment variables (process-scoped)
+- **Production**: Use HTTPS for HTTP transport in production environments
+- **Token Format**: All FormBro API tokens start with `fb_`
+
 ## License
 
 MIT
@@ -164,3 +495,10 @@ MIT
 - [FormBro](https://formbro.com)
 - [Model Context Protocol](https://modelcontextprotocol.io)
 - [npm Package](https://www.npmjs.com/package/formbro-mcp-server)
+- [GitHub Repository](https://github.com/jackyzhang69/formbro/tree/main/mcp-server)
+
+## Support
+
+For issues and questions:
+- GitHub Issues: https://github.com/jackyzhang69/formbro/issues
+- FormBro Support: support@formbro.com

package/dist/index.js

@@ -21,9 +21,34 @@ import { registerApplicantTools } from "./tools/applicants.js";
 import { registerApplicationTools } from "./tools/applications.js";
 import { registerEmployerTools } from "./tools/employers.js";
 import { registerFindTool } from "./tools/find.js";
+import { registerSystemTools } from "./tools/system.js";
+import { registerReadExtraTools } from "./tools/applications-extra.js";
+import { registerValidateTools } from "./tools/validate.js";
+import { registerWriteTools } from "./tools/write.js";
+import { registerPatchTools } from "./tools/patch.js";
+import { registerAuditTools } from "./tools/audit.js";
+import { registerExtractTools } from "./tools/extract.js";
+import { registerExportTools } from "./tools/export.js";
+// Toolset configuration
+const TOOLSETS = ["system", "read", "validate", "write", "patch", "extract", "export", "audit"];
+const DEFAULT_TOOLSETS = ["system", "read", "validate"];
+function parseToolsetsFromFlag() {
+    const flag = process.argv.find((a) => a.startsWith("--toolsets="))?.split("=")[1];
+    if (!flag)
+        return new Set(DEFAULT_TOOLSETS);
+    return new Set(flag.split(",").filter((t) => TOOLSETS.includes(t)));
+}
+function parseToolsetsFromQuery(query) {
+    if (!query)
+        return parseToolsetsFromFlag();
+    const requested = new Set(query.split(",").filter((t) => TOOLSETS.includes(t)));
+    return requested.size > 0 ? requested : parseToolsetsFromFlag();
+}
+// Used for stdio mode (startup-time only)
+const enabledToolsets = parseToolsetsFromFlag();
 // Server configuration
 const SERVER_NAME = "formbro-mcp-server";
-const SERVER_VERSION = "1.0.0";
+const SERVER_VERSION = "1.0.2";
 /**
  * Validate required environment variables for STDIO mode
  */
@@ -56,18 +81,35 @@ function validateEnvironmentHttp() {
     return { apiUrl };
 }
 /**
- * Create and configure the MCP server
+ * Create and configure the MCP server with the given toolsets
  */
-function createServer() {
+function createServer(toolsets = enabledToolsets) {
     const server = new McpServer({
         name: SERVER_NAME,
         version: SERVER_VERSION
     });
-    // Register all tools
-    registerFindTool(server); // Smart find tool - recommended for most queries
-    registerApplicantTools(server);
-    registerApplicationTools(server);
-    registerEmployerTools(server);
+    // Register tools based on enabled toolsets
+    if (toolsets.has("system"))
+        registerSystemTools(server);
+    if (toolsets.has("read")) {
+        registerFindTool(server);
+        registerApplicantTools(server);
+        registerApplicationTools(server);
+        registerEmployerTools(server);
+        registerReadExtraTools(server);
+    }
+    if (toolsets.has("validate"))
+        registerValidateTools(server);
+    if (toolsets.has("write"))
+        registerWriteTools(server);
+    if (toolsets.has("patch"))
+        registerPatchTools(server);
+    if (toolsets.has("audit"))
+        registerAuditTools(server);
+    if (toolsets.has("extract"))
+        registerExtractTools(server);
+    if (toolsets.has("export"))
+        registerExportTools(server);
     return server;
 }
 /**
@@ -135,9 +177,11 @@ async function runHttp() {
             }
             // Create API client with the provided token
             const apiClient = createApiClientWithToken(token);
+            // Parse toolsets from query param (default: system,read,validate)
+            const toolsets = parseToolsetsFromQuery(req.query.toolsets);
             // Run the MCP request with the token-specific API client
             await runWithApiClient(apiClient, async () => {
-                const server = createServer();
+                const server = createServer(toolsets);
                 // Create new transport for each request (stateless)
                 const transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: undefined,
@@ -236,8 +280,8 @@ ENVIRONMENT VARIABLES:
   FORMBRO_API_URL     Base URL of FormBro API (required)
                       Example: https://api.formbro.com
 
-  FORMBRO_API_TOKEN   Your FormBro API token (required)
-                      Get this from FormBro settings
+  FORMBRO_API_TOKEN   Your FormBro API token
+                      Required for stdio mode
 
   TRANSPORT           Transport mode (optional, default: stdio)
                       - stdio: For local CLI integration
@@ -252,9 +296,8 @@ EXAMPLES:
   FORMBRO_API_TOKEN=your-token \\
   formbro-mcp-server
 
-  # Run with HTTP transport (for remote access)
+  # Run with HTTP transport
   FORMBRO_API_URL=https://api.formbro.com \\
-  FORMBRO_API_TOKEN=your-token \\
   TRANSPORT=http \\
   PORT=8080 \\
   formbro-mcp-server
@@ -270,7 +313,8 @@ AVAILABLE TOOLS:
 
 CONNECTING FROM CLAUDE CODE:
   # For HTTP transport
-  claude mcp add --transport http formbro http://localhost:3000/mcp
+  claude mcp add --transport http formbro http://localhost:3000/mcp \\
+    --header "Authorization: Bearer YOUR_FORMBRO_API_TOKEN"
 
   # For stdio transport
   claude mcp add --transport stdio formbro -- \\