@docrouter/mcp 0.1.0 → 0.1.2

package/CLAUDE.md

@@ -0,0 +1,129 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when using DocRouter MCP tools.
+
+## Working with DocRouter MCP Tools
+
+### CRITICAL: Always Call Help Tools First
+
+Before creating or modifying DocRouter resources, **ALWAYS** follow this workflow:
+
+1. **Call help tools FIRST**:
+   - `mcp__docrouter__help_schemas()` - Before creating/modifying schemas
+   - `mcp__docrouter__help_prompts()` - Before creating/modifying prompts
+   - `mcp__docrouter__help_forms()` - Before creating/modifying forms
+   - `mcp__docrouter__help()` - For general API guidance
+
+2. **Validate before creating**:
+   - `mcp__docrouter__validate_schema(schema)` - ALWAYS validate schemas before creating them
+   - `mcp__docrouter__validate_form(form)` - ALWAYS validate forms before creating them
+   - Check the validation response for errors and fix any issues
+
+3. **Then create the resource**:
+   - Only after help and validation, create the resource
+
+### Schema Creation Rules
+
+**CRITICAL**: OpenAI's strict mode requires:
+
+- **ALL properties in an object MUST be in the `required` array** (even optional fields)
+- Use `additionalProperties: false` for strict validation
+- All nested objects must follow the same rules
+- Never create a schema without validating it first
+
+**Wrong** (will fail):
+```json
+{
+  "properties": {
+    "personal_info": {
+      "properties": {
+        "name": {"type": "string"},
+        "phone": {"type": "string"}
+      },
+      "required": ["name"]  // ❌ Missing "phone" in required
+    }
+  }
+}
+```
+
+**Correct**:
+```json
+{
+  "properties": {
+    "personal_info": {
+      "properties": {
+        "name": {"type": "string"},
+        "phone": {"type": "string"}
+      },
+      "required": ["name", "phone"]  // ✅ ALL properties listed
+    }
+  }
+}
+```
+
+### Mandatory Workflow for Schema Creation
+
+```
+1. mcp__docrouter__help_schemas()       // Read the documentation
+2. mcp__docrouter__validate_schema()    // Validate your schema
+3. Fix any validation errors
+4. mcp__docrouter__create_schema()      // Only if validation passes
+```
+
+### Mandatory Workflow for Form Creation
+
+```
+1. mcp__docrouter__help_forms()         // Read the documentation
+2. mcp__docrouter__validate_form()      // Validate your form
+3. Fix any validation errors
+4. mcp__docrouter__create_form()        // Only if validation passes
+```
+
+### Form Creation Rules
+
+**CRITICAL**: Form.io forms in DocRouter require:
+
+- **`json_formio` array** - Must contain array of Form.io component definitions
+- **Unique field keys** - Each input field must have a unique `key` property
+- **Valid component types** - Use standard Form.io types (textfield, email, number, select, etc.)
+- **Proper nested structures** - Panels, columns, and fieldsets must have `components` arrays
+- **Field mappings (optional)** - If using `json_formio_mapping`, ensure all references are valid
+
+**Wrong** (will fail):
+```json
+{
+  "json_formio": [
+    {
+      "type": "textfield",
+      "label": "Name"
+      // ❌ Missing "key" field
+    }
+  ]
+}
+```
+
+**Correct**:
+```json
+{
+  "json_formio": [
+    {
+      "type": "textfield",
+      "key": "candidate_name",
+      "label": "Candidate Name",
+      "input": true,
+      "validate": {
+        "required": true
+      }
+    }
+  ]
+}
+```
+
+### Never Skip Validation
+
+**NEVER** call `create_schema`, `create_prompt`, or `create_form` without:
+1. Reading the help documentation first
+2. Validating the schema/form/structure first
+3. Confirming validation succeeded
+
+This prevents wasted time and ensures resources are created correctly on the first attempt.

package/README.md

@@ -2,6 +2,32 @@
 
 A TypeScript-based Model Context Protocol (MCP) server for DocRouter API integration.
 
+## Quick Start
+
+```bash
+# Install the package
+npm install @docrouter/mcp
+
+# Configure with your DocRouter credentials
+export DOCROUTER_ORG_ID="your-org-id"
+export DOCROUTER_ORG_API_TOKEN="your-token"
+
+# Use in your MCP client configuration
+```
+
+## Publishing Quick Reference
+
+```bash
+# Build and test
+npm run build && npm test
+
+# Update version and publish
+npm version patch && npm publish
+
+# Check published package
+npm view @docrouter/mcp
+```
+
 ## Overview
 
 This MCP server provides AI applications with access to DocRouter's document processing capabilities, including:
@@ -14,7 +40,25 @@ This MCP server provides AI applications with access to DocRouter's document pro
 
 ## Installation
 
+### For Users
+
+Install the published package:
+
 ```bash
+# Install locally
+npm install @docrouter/mcp
+
+# Or install globally
+npm install -g @docrouter/mcp
+```
+
+### For Developers
+
+Clone and install dependencies:
+
+```bash
+git clone <repository-url>
+cd docrouter-mcp
 npm install
 ```
 
@@ -114,17 +158,36 @@ const guide = await docrouter_document_analysis_guide("document-id");
 
 ## Integration with AI Applications
 
-### Claude Desktop
+### Prerequisites
 
-Add to your `claude_desktop_config.json`:
+Before configuring MCP integration, ensure you have:
+
+1. **Installed the package**:
+   ```bash
+   npm install @docrouter/mcp
+   ```
+
+2. **DocRouter credentials**:
+   - `DOCROUTER_ORG_ID` - Your DocRouter organization ID
+   - `DOCROUTER_ORG_API_TOKEN` - Your DocRouter organization API token
+   - `DOCROUTER_API_URL` - DocRouter API URL (optional, defaults to production)
+
+### Configuration Files
+
+The MCP server can be configured using different configuration files depending on your AI application:
+
+#### For Cursor IDE
+
+Create `.mcp.json` in your project root:
 
 ```json
 {
   "mcpServers": {
     "docrouter": {
       "command": "node",
-      "args": ["/path/to/docrouter-mcp/dist/index.js"],
+      "args": ["node_modules/@docrouter/mcp/dist/index.js"],
       "env": {
+        "DOCROUTER_API_URL": "https://app.docrouter.ai/fastapi",
         "DOCROUTER_ORG_ID": "your-org-id",
         "DOCROUTER_ORG_API_TOKEN": "your-token"
       }
@@ -133,17 +196,18 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-### Cursor
+#### For Claude Desktop
 
-Create `.cursor/mcp.json` in your project root:
+Add to your `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "docrouter": {
       "command": "node",
-      "args": ["/path/to/docrouter-mcp/dist/index.js"],
+      "args": ["node_modules/@docrouter/mcp/dist/index.js"],
       "env": {
+        "DOCROUTER_API_URL": "https://app.docrouter.ai/fastapi",
         "DOCROUTER_ORG_ID": "your-org-id",
         "DOCROUTER_ORG_API_TOKEN": "your-token"
       }
@@ -152,7 +216,7 @@ Create `.cursor/mcp.json` in your project root:
 }
 ```
 
-### Claude Code
+#### For Claude Code
 
 Create a `.mcp.conf` file in your project root:
 
@@ -161,8 +225,9 @@ Create a `.mcp.conf` file in your project root:
   "mcpServers": {
     "docrouter": {
       "command": "node",
-      "args": ["/path/to/docrouter-mcp/dist/index.js"],
+      "args": ["node_modules/@docrouter/mcp/dist/index.js"],
       "env": {
+        "DOCROUTER_API_URL": "https://app.docrouter.ai/fastapi",
         "DOCROUTER_ORG_ID": "your-org-id",
         "DOCROUTER_ORG_API_TOKEN": "your-token"
       }
@@ -171,6 +236,152 @@ Create a `.mcp.conf` file in your project root:
 }
 ```
 
+### Using Global Installation
+
+If you installed the package globally, you can use the binary directly:
+
+```json
+{
+  "mcpServers": {
+    "docrouter": {
+      "command": "docrouter-mcp",
+      "env": {
+        "DOCROUTER_API_URL": "https://app.docrouter.ai/fastapi",
+        "DOCROUTER_ORG_ID": "your-org-id",
+        "DOCROUTER_ORG_API_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+### Step-by-Step Setup Guide
+
+#### 1. Install the Package
+
+```bash
+# In your project directory
+npm install @docrouter/mcp
+```
+
+#### 2. Create Configuration File
+
+For **Cursor IDE**, create `.mcp.json` in your project root:
+
+```bash
+# Create the configuration file
+touch .mcp.json
+```
+
+#### 3. Add Configuration Content
+
+Copy the appropriate configuration from above and replace:
+- `your-org-id` with your actual DocRouter organization ID
+- `your-token` with your actual DocRouter API token
+- `https://app.docrouter.ai/fastapi` with your API URL (if different)
+
+#### 4. Verify Installation
+
+Check that the package files exist:
+
+```bash
+# Verify the main file exists
+ls -la node_modules/@docrouter/mcp/dist/index.js
+
+# Check package contents
+ls -la node_modules/@docrouter/mcp/dist/
+```
+
+#### 5. Test the Configuration
+
+You can test the MCP server manually:
+
+```bash
+# Set environment variables
+export DOCROUTER_ORG_ID="your-org-id"
+export DOCROUTER_ORG_API_TOKEN="your-token"
+
+# Run the server directly
+node node_modules/@docrouter/mcp/dist/index.js
+```
+
+### Troubleshooting MCP Connection
+
+#### Common Issues and Solutions
+
+**1. "MCP server not connecting"**
+
+- ✅ **Check file paths**: Ensure `node_modules/@docrouter/mcp/dist/index.js` exists
+- ✅ **Verify package installation**: Run `npm list @docrouter/mcp`
+- ✅ **Check configuration syntax**: Validate your JSON configuration
+- ✅ **Test manually**: Run the server directly to check for errors
+
+**2. "Command not found"**
+
+- ✅ **Use absolute paths**: Use full paths instead of relative ones
+- ✅ **Check Node.js**: Ensure Node.js is in your PATH
+- ✅ **Verify permissions**: Ensure the file is executable
+
+**3. "Environment variables not set"**
+
+- ✅ **Check variable names**: Use exact names: `DOCROUTER_ORG_ID`, `DOCROUTER_ORG_API_TOKEN`
+- ✅ **Verify values**: Ensure credentials are correct and not expired
+- ✅ **Test API access**: Verify your credentials work with DocRouter API
+
+**4. "Permission denied"**
+
+- ✅ **Check file permissions**: Ensure the file is readable
+- ✅ **Run as correct user**: Don't use sudo for MCP servers
+- ✅ **Check directory permissions**: Ensure access to the project directory
+
+#### Debug Configuration
+
+Add debug logging to your configuration:
+
+```json
+{
+  "mcpServers": {
+    "docrouter": {
+      "command": "node",
+      "args": ["node_modules/@docrouter/mcp/dist/index.js"],
+      "env": {
+        "DOCROUTER_API_URL": "https://app.docrouter.ai/fastapi",
+        "DOCROUTER_ORG_ID": "your-org-id",
+        "DOCROUTER_ORG_API_TOKEN": "your-token",
+        "DEBUG": "mcp:*"
+      }
+    }
+  }
+}
+```
+
+#### Example Working Configuration
+
+Here's a complete example for Cursor IDE:
+
+```json
+{
+  "mcpServers": {
+    "docrouter": {
+      "command": "node",
+      "args": ["node_modules/@docrouter/mcp/dist/index.js"],
+      "env": {
+        "DOCROUTER_API_URL": "http://localhost:8000",
+        "DOCROUTER_ORG_ID": "679c9a914cfaaaa3640811ed",
+        "DOCROUTER_ORG_API_TOKEN": "LK8RyD5OKn8taDQCbozI5payDk2xXqnW2SXXPZgMp88"
+      }
+    }
+  }
+}
+```
+
+### Security Notes
+
+- 🔒 **Never commit credentials**: Add `.mcp.json` to `.gitignore` if it contains real credentials
+- 🔒 **Use environment variables**: Consider using system environment variables instead of hardcoded values
+- 🔒 **Rotate tokens regularly**: Update your API tokens periodically
+- 🔒 **Limit token permissions**: Use tokens with minimal required permissions
+
 ## Development
 
 ### Prerequisites
@@ -178,12 +389,15 @@ Create a `.mcp.conf` file in your project root:
 - Node.js 18+
 - TypeScript 5+
 - Access to DocRouter API
+- npm account with publish permissions
 
 ### Scripts
 
 - `npm run build` - Build the project
 - `npm run dev` - Build in watch mode
 - `npm run start:dev` - Run in development mode
+- `npm test` - Run test suite
+- `npm run test:watch` - Run tests in watch mode
 - `npm run lint` - Run ESLint
 - `npm run type-check` - Run TypeScript type checking
 
@@ -192,12 +406,155 @@ Create a `.mcp.conf` file in your project root:
 ```
 src/
 ├── index.ts          # Main MCP server implementation
+tests/
+├── mcp-functionality.test.ts  # MCP functionality tests
+├── mcp-server.test.ts         # Server integration tests
+├── setup.ts                   # Test setup configuration
 package.json          # Package configuration
 tsconfig.json         # TypeScript configuration
 tsup.config.ts        # Build configuration
+jest.config.js        # Jest test configuration
 README.md             # This file
 ```
 
+## Publishing
+
+### Prerequisites for Publishing
+
+1. **npm Account**: Ensure you have an npm account and are logged in
+2. **Organization Access**: You need publish permissions for the `@docrouter` organization
+3. **Clean Working Directory**: All changes should be committed
+
+### Publishing Steps
+
+#### 1. Login to npm
+
+```bash
+npm login
+```
+
+Verify you're logged in:
+
+```bash
+npm whoami
+```
+
+#### 2. Prepare for Publishing
+
+```bash
+# Build the project
+npm run build
+
+# Run tests to ensure everything works
+npm test
+
+# Check what will be published
+npm pack --dry-run
+```
+
+#### 3. Version Management
+
+Update the version number in `package.json`:
+
+```bash
+# For bug fixes
+npm version patch
+
+# For new features (backward compatible)
+npm version minor
+
+# For breaking changes
+npm version major
+```
+
+Or manually edit the version in `package.json`.
+
+#### 4. Publish the Package
+
+```bash
+npm publish
+```
+
+#### 5. Verify Publication
+
+Check that your package is available:
+
+```bash
+# View package info
+npm view @docrouter/mcp
+
+# Test installation
+npm install @docrouter/mcp
+```
+
+### Package Configuration
+
+The package is configured as a scoped package with the following key settings:
+
+```json
+{
+  "name": "@docrouter/mcp",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}
+```
+
+### What Gets Published
+
+The following files are included in the published package:
+
+- `dist/` - Built JavaScript files (CommonJS + ES Modules)
+- `dist/docs/knowledge_base/` - Bundled knowledge base files
+- `README.md` - Documentation
+- `package.json` - Package metadata
+
+### Updating the Package
+
+To publish updates:
+
+1. Make your changes
+2. Update the version: `npm version patch|minor|major`
+3. Build and test: `npm run build && npm test`
+4. Publish: `npm publish`
+
+### Troubleshooting
+
+#### Package Already Exists
+If you get an error that the package already exists:
+- Check the version number - it must be unique
+- Use `npm version patch` to increment the version
+
+#### Permission Denied
+If you get permission errors:
+- Ensure you're logged in: `npm whoami`
+- Check you have publish permissions for `@docrouter` organization
+- Contact the organization admin if needed
+
+#### Build Errors
+If the build fails:
+- Check TypeScript errors: `npm run type-check`
+- Ensure all dependencies are installed: `npm install`
+- Check the `tsup.config.ts` configuration
+
+### Unpublishing (Emergency Only)
+
+⚠️ **Warning**: Only unpublish within 72 hours and if absolutely necessary.
+
+```bash
+# Unpublish a specific version
+npm unpublish @docrouter/mcp@0.1.0
+
+# Unpublish entire package (use with caution)
+npm unpublish @docrouter/mcp --force
+```
+
+**Note**: Unpublishing blocks republishing the same version for 24 hours.
+
 ## Error Handling
 
 The server includes comprehensive error handling and will return structured error responses for debugging. All errors are logged to stderr to avoid interfering with MCP communication.

package/dist/CLAUDE.md

@@ -0,0 +1,129 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when using DocRouter MCP tools.
+
+## Working with DocRouter MCP Tools
+
+### CRITICAL: Always Call Help Tools First
+
+Before creating or modifying DocRouter resources, **ALWAYS** follow this workflow:
+
+1. **Call help tools FIRST**:
+   - `mcp__docrouter__help_schemas()` - Before creating/modifying schemas
+   - `mcp__docrouter__help_prompts()` - Before creating/modifying prompts
+   - `mcp__docrouter__help_forms()` - Before creating/modifying forms
+   - `mcp__docrouter__help()` - For general API guidance
+
+2. **Validate before creating**:
+   - `mcp__docrouter__validate_schema(schema)` - ALWAYS validate schemas before creating them
+   - `mcp__docrouter__validate_form(form)` - ALWAYS validate forms before creating them
+   - Check the validation response for errors and fix any issues
+
+3. **Then create the resource**:
+   - Only after help and validation, create the resource
+
+### Schema Creation Rules
+
+**CRITICAL**: OpenAI's strict mode requires:
+
+- **ALL properties in an object MUST be in the `required` array** (even optional fields)
+- Use `additionalProperties: false` for strict validation
+- All nested objects must follow the same rules
+- Never create a schema without validating it first
+
+**Wrong** (will fail):
+```json
+{
+  "properties": {
+    "personal_info": {
+      "properties": {
+        "name": {"type": "string"},
+        "phone": {"type": "string"}
+      },
+      "required": ["name"]  // ❌ Missing "phone" in required
+    }
+  }
+}
+```
+
+**Correct**:
+```json
+{
+  "properties": {
+    "personal_info": {
+      "properties": {
+        "name": {"type": "string"},
+        "phone": {"type": "string"}
+      },
+      "required": ["name", "phone"]  // ✅ ALL properties listed
+    }
+  }
+}
+```
+
+### Mandatory Workflow for Schema Creation
+
+```
+1. mcp__docrouter__help_schemas()       // Read the documentation
+2. mcp__docrouter__validate_schema()    // Validate your schema
+3. Fix any validation errors
+4. mcp__docrouter__create_schema()      // Only if validation passes
+```
+
+### Mandatory Workflow for Form Creation
+
+```
+1. mcp__docrouter__help_forms()         // Read the documentation
+2. mcp__docrouter__validate_form()      // Validate your form
+3. Fix any validation errors
+4. mcp__docrouter__create_form()        // Only if validation passes
+```
+
+### Form Creation Rules
+
+**CRITICAL**: Form.io forms in DocRouter require:
+
+- **`json_formio` array** - Must contain array of Form.io component definitions
+- **Unique field keys** - Each input field must have a unique `key` property
+- **Valid component types** - Use standard Form.io types (textfield, email, number, select, etc.)
+- **Proper nested structures** - Panels, columns, and fieldsets must have `components` arrays
+- **Field mappings (optional)** - If using `json_formio_mapping`, ensure all references are valid
+
+**Wrong** (will fail):
+```json
+{
+  "json_formio": [
+    {
+      "type": "textfield",
+      "label": "Name"
+      // ❌ Missing "key" field
+    }
+  ]
+}
+```
+
+**Correct**:
+```json
+{
+  "json_formio": [
+    {
+      "type": "textfield",
+      "key": "candidate_name",
+      "label": "Candidate Name",
+      "input": true,
+      "validate": {
+        "required": true
+      }
+    }
+  ]
+}
+```
+
+### Never Skip Validation
+
+**NEVER** call `create_schema`, `create_prompt`, or `create_form` without:
+1. Reading the help documentation first
+2. Validating the schema/form/structure first
+3. Confirming validation succeeded
+
+This prevents wasted time and ensures resources are created correctly on the first attempt.