@zudello/modelcontextprotocol 1.0.0 → 1.1.0

package/README.md

@@ -1,238 +1,62 @@
 # Zudello MCP Server
 
-Model Context Protocol (MCP) server exposing **106 Zudello ERP automation tools** for use with Claude Desktop and other MCP-compatible clients.
-
-## ✅ Implementation Status
-
-**Complete**: All 106 tools successfully migrated from inapp-chat to MCP format.
+Model Context Protocol (MCP) server exposing **106 Zudello ERP automation tools** for use with Claude Desktop, Claude Code CLI, and other MCP-compatible clients.
 
 ## Features
 
 - **106 Zudello Tools**: Complete access to Zudello ERP operations
   - 65 read-only tools for data access and discovery
   - 41 write tools with approval metadata
-- **Multi-tenant Support**: Environment-based auth for stdio mode
+- **Multi-tenant Support**: Environment-based authentication
 - **Approval Workflow**: Write operations return approval metadata with risk levels
 - **Type-Safe**: Full TypeScript implementation with strict types
 - **ESM Modules**: Modern ES module architecture
 
 ## Installation
 
-```bash
-npm install
-npm run build
-```
-
-## Configuration
-
-### Environment Variables
+### Using npx (Recommended)
 
-Create a `.env` file with your Zudello credentials:
+No installation required - use directly with npx:
 
 ```bash
-ZUDELLO_TOKEN=your_jwt_token_here
-ZUDELLO_ORGANIZATION=your_org_uuid_here
-ZUDELLO_TEAM=your_team_uuid_here
-ZUDELLO_CLUSTER_URL=api.1.eur1.zudello.io  # Optional, defaults shown
-AUTHENTICATION_API_BASE=api.1.global.zudello.io  # Optional, for org-level API (defaults shown)
-LOG_LEVEL=info  # Optional: debug, info, warn, error
-```
-
-### Claude Desktop Setup
-
-**IMPORTANT**: Always use absolute paths (not `~` or relative paths) in your configuration.
-
-#### macOS Configuration
-
-Config file location: `~/Library/Application Support/Claude/claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "zudello": {
-      "command": "node",
-      "args": ["/absolute/path/to/research_mcp/dist/index.js"],
-      "env": {
-        "ZUDELLO_TOKEN": "your_jwt_token",
-        "ZUDELLO_ORGANIZATION": "your_org_uuid",
-        "ZUDELLO_TEAM": "your_team_uuid",
-        "ZUDELLO_CLUSTER_URL": "api.1.eur1.zudello.io",
-        "AUTHENTICATION_API_BASE": "api.1.global.zudello.io"
-      }
-    }
-  }
-}
-```
-
-**Example with actual path**:
-```json
-{
-  "mcpServers": {
-    "zudello": {
-      "command": "node",
-      "args": ["/Users/yourname/projects/research_mcp/dist/index.js"],
-      "env": {
-        "ZUDELLO_TOKEN": "eyJ...",
-        "ZUDELLO_ORGANIZATION": "d49d2841-5cc4-4ffc-9be2-d07900eb1ffb",
-        "ZUDELLO_TEAM": "19078156-f3cf-41eb-a9b4-984f84c24b35",
-        "ZUDELLO_CLUSTER_URL": "api.au.3.zudello.io"
-      }
-    }
-  }
-}
-```
-
-#### Linux Configuration
-
-Config file location: `~/.config/claude/claude_desktop_config.json`
-
-Use the same JSON structure as macOS above.
-
-#### Windows Configuration
-
-Config file location: `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "zudello": {
-      "command": "node",
-      "args": ["C:\\path\\to\\research_mcp\\dist\\index.js"],
-      "env": {
-        "ZUDELLO_TOKEN": "your_jwt_token",
-        "ZUDELLO_ORGANIZATION": "your_org_uuid",
-        "ZUDELLO_TEAM": "your_team_uuid",
-        "ZUDELLO_CLUSTER_URL": "api.1.eur1.zudello.io"
-      }
-    }
-  }
-}
+npx @zudello/modelcontextprotocol
 ```
 
-### Claude Code (CLI) Setup
-
-**IMPORTANT**: Always use absolute paths (not `~` or relative paths) in your configuration.
+### Global Installation
 
-#### macOS/Linux Configuration
+Install globally to use without npx prefix:
 
-Config file location: `~/.config/claude-code/mcp_servers.json`
-
-```json
-{
-  "mcpServers": {
-    "zudello": {
-      "command": "node",
-      "args": ["/absolute/path/to/research_mcp/dist/index.js"],
-      "env": {
-        "ZUDELLO_TOKEN": "your_jwt_token",
-        "ZUDELLO_ORGANIZATION": "your_org_uuid",
-        "ZUDELLO_TEAM": "your_team_uuid",
-        "ZUDELLO_CLUSTER_URL": "api.1.eur1.zudello.io",
-        "AUTHENTICATION_API_BASE": "api.1.global.zudello.io"
-      }
-    }
-  }
-}
+```bash
+npm install -g @zudello/modelcontextprotocol
 ```
 
-#### Windows Configuration
-
-Config file location: `%APPDATA%\claude-code\mcp_servers.json`
-
-Use the same JSON structure as above.
-
-### Getting Your Credentials
-
-1. **ZUDELLO_TOKEN**: JWT authentication token (starts with "eyJ")
-   - Obtain from your Zudello account settings or API section
-
-2. **ZUDELLO_ORGANIZATION**: Your organization UUID
-   - Format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
-
-3. **ZUDELLO_TEAM**: Your team UUID
-   - Format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
+## Quick Start
 
-4. **ZUDELLO_CLUSTER_URL**: Your region-specific API cluster
-   - Examples: `api.1.eur1.zudello.io` (Europe), `api.au.3.zudello.io` (Australia), `api.us.1.zudello.io` (US)
-   - Check your Zudello instance URL to determine your cluster
+### 1. Get Your Zudello Credentials
 
-### Setup Steps
+You'll need the following from your Zudello account:
 
-1. **Build the project** (required before first use):
-   ```bash
-   cd /path/to/research_mcp
-   npm install
-   npm run build
-   ```
+- **ZUDELLO_TOKEN**: JWT authentication token (starts with "eyJ")
+- **ZUDELLO_ORGANIZATION**: Organization UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
+- **ZUDELLO_TEAM**: Team UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
+- **ZUDELLO_CLUSTER_URL**: Your region-specific API cluster
+  - Examples: `api.1.eur1.zudello.io` (Europe), `api.au.3.zudello.io` (Australia), `api.us.1.zudello.io` (US)
+  - Check your Zudello instance URL to determine your cluster
 
-2. **Create/edit config file** with your credentials (see paths above)
+### 2. Configure Claude Desktop
 
-3. **Restart Claude** (Desktop or Code)
+Add the MCP server to your Claude Desktop configuration file:
 
-4. **Verify installation**:
-   - Ask Claude: "What Zudello MCP tools are available?"
-   - You should see a list of 106 tools
+#### macOS
+File location: `~/Library/Application Support/Claude/claude_desktop_config.json`
 
-### Troubleshooting
+#### Linux
+File location: `~/.config/claude/claude_desktop_config.json`
 
-**"Server not found" or "Connection failed"**:
-- Verify the path to `dist/index.js` is absolute (not relative or using `~`)
-- Ensure you ran `npm run build` after installation
-- Check that Node.js is in your PATH: `which node` or `node --version`
-
-**"Invalid credentials" or authentication errors**:
-- Verify your ZUDELLO_TOKEN starts with "eyJ"
-- Check ORGANIZATION and TEAM UUIDs are correct format
-- Confirm CLUSTER_URL matches your Zudello instance region
-
-**"ZodError" or validation errors**:
-- This was a bug in versions before the logger fix - ensure you have the latest code
-- Logs must go to stderr, not stdout (fixed in current version)
-
-**Changes not taking effect**:
-- Always restart Claude Desktop/Code after config changes
-- Run `npm run build` after any code changes
-
-## NPM Package Installation
-
-### Installing from NPM Registry
-
-Once published, you can install the package globally or use it with npx:
-
-#### Global Installation
-```bash
-npm install -g @zudello/modelcontextprotocol
-```
-
-#### Using with npx (no installation)
-```bash
-npx @zudello/modelcontextprotocol
-```
-
-### Using NPM Package with Claude Desktop
-
-After installing the npm package, configure Claude Desktop to use it:
-
-#### macOS (`~/Library/Application Support/Claude/claude_desktop_config.json`)
-```json
-{
-  "mcpServers": {
-    "zudello": {
-      "command": "npx",
-      "args": ["@zudello/modelcontextprotocol"],
-      "env": {
-        "ZUDELLO_TOKEN": "your_jwt_token",
-        "ZUDELLO_ORGANIZATION": "your_org_uuid",
-        "ZUDELLO_TEAM": "your_team_uuid",
-        "ZUDELLO_CLUSTER_URL": "api.1.eur1.zudello.io",
-        "AUTHENTICATION_API_BASE": "api.1.global.zudello.io"
-      }
-    }
-  }
-}
-```
+#### Windows
+File location: `%APPDATA%\Claude\claude_desktop_config.json`
 
-#### Linux (`~/.config/claude/claude_desktop_config.json`)
+**Configuration:**
 ```json
 {
   "mcpServers": {
@@ -251,49 +75,17 @@ After installing the npm package, configure Claude Desktop to use it:
 }
 ```
 
-#### Windows (`%APPDATA%\Claude\claude_desktop_config.json`)
-```json
-{
-  "mcpServers": {
-    "zudello": {
-      "command": "npx",
-      "args": ["@zudello/modelcontextprotocol"],
-      "env": {
-        "ZUDELLO_TOKEN": "your_jwt_token",
-        "ZUDELLO_ORGANIZATION": "your_org_uuid",
-        "ZUDELLO_TEAM": "your_team_uuid",
-        "ZUDELLO_CLUSTER_URL": "api.1.eur1.zudello.io",
-        "AUTHENTICATION_API_BASE": "api.1.global.zudello.io"
-      }
-    }
-  }
-}
-```
+### 3. Configure Claude Code CLI
 
-### Using NPM Package with Claude Code
+Add the MCP server to your Claude Code configuration file:
 
-When using the npm package with Claude Code CLI:
+#### macOS/Linux
+File location: `~/.config/claude-code/mcp_servers.json`
 
-#### macOS/Linux (`~/.config/claude-code/mcp_servers.json`)
-```json
-{
-  "mcpServers": {
-    "zudello": {
-      "command": "npx",
-      "args": ["@zudello/modelcontextprotocol"],
-      "env": {
-        "ZUDELLO_TOKEN": "your_jwt_token",
-        "ZUDELLO_ORGANIZATION": "your_org_uuid",
-        "ZUDELLO_TEAM": "your_team_uuid",
-        "ZUDELLO_CLUSTER_URL": "api.1.eur1.zudello.io",
-        "AUTHENTICATION_API_BASE": "api.1.global.zudello.io"
-      }
-    }
-  }
-}
-```
+#### Windows
+File location: `%APPDATA%\claude-code\mcp_servers.json`
 
-#### Windows (`%APPDATA%\claude-code\mcp_servers.json`)
+**Configuration:**
 ```json
 {
   "mcpServers": {
@@ -312,119 +104,38 @@ When using the npm package with Claude Code CLI:
 }
 ```
 
-## Publishing to NPM
-
-For maintainers who want to publish this package to npm:
+### 4. Restart Claude
 
-### Prerequisites
-1. **NPM Account**: Create account at https://www.npmjs.com
-2. **NPM Login**: Run `npm login` and authenticate
-3. **Package Scope**: Ensure you have access to `@zudello` scope (or update package name)
-
-### Publishing Steps
-
-```bash
-# 1. Ensure you're on the correct branch
-git checkout main  # or develop, depending on your workflow
+Restart Claude Desktop or Claude Code CLI to load the new configuration.
 
-# 2. Update version (optional - creates git tag)
-npm version patch  # or minor, major
-# This updates package.json and creates a git tag
+### 5. Verify Installation
 
-# 3. Build and validate
-npm run build
-npm run typecheck
+Ask Claude: "What Zudello MCP tools are available?"
 
-# 4. Test the package locally (optional but recommended)
-npm pack  # Creates a tarball
-npm install -g ./zudello-mcp-server-1.0.0.tgz  # Test install
-zudello-mcp --help  # Test binary
+You should see a list of 106 available tools.
 
-# 5. Publish to npm
-npm publish --access public
-# Use --access public for scoped packages (@zudello/*)
+## Configuration Details
 
-# 6. Push git tags
-git push --tags
-```
-
-### Version Management
-
-Follow semantic versioning (semver):
-- **Patch** (1.0.X): Bug fixes, documentation updates
-- **Minor** (1.X.0): New features, backward-compatible
-- **Major** (X.0.0): Breaking changes
-
-```bash
-npm version patch  # 1.0.0 → 1.0.1
-npm version minor  # 1.0.1 → 1.1.0
-npm version major  # 1.1.0 → 2.0.0
-```
-
-### NPM Package Contents
-
-The published package includes:
-- `dist/` - Compiled JavaScript and TypeScript definitions
-- `README.md` - Full documentation
-- `TOOL_CATALOG.md` - Complete tool reference
-- `QUICKSTART.md` - Quick start guide
-- `LICENSE` - MIT license
-
-Excluded from package (see `.npmignore` or package.json `files`):
-- `src/` - TypeScript source files
-- `node_modules/` - Dependencies
-- `.env` - Local configuration
-- Development files
-
-### Publishing Checklist
-
-Before publishing:
-- ✅ All tests pass (`npm test`)
-- ✅ TypeScript compiles without errors (`npm run typecheck`)
-- ✅ Build succeeds (`npm run build`)
-- ✅ README.md is up to date
-- ✅ CHANGELOG.md documents changes (if maintained)
-- ✅ Version number is updated
-- ✅ Git working directory is clean
-- ✅ You're logged into npm (`npm whoami`)
-
-### Unpublishing (Emergency Only)
-
-If you need to unpublish (not recommended):
-```bash
-# Unpublish specific version (within 72 hours of publish)
-npm unpublish @zudello/modelcontextprotocol@1.0.0
-
-# Deprecate instead (preferred)
-npm deprecate @zudello/modelcontextprotocol@1.0.0 "Use version 1.0.1 instead"
-```
-
-### Alternative: Private NPM Registry
+### Environment Variables
 
-For private/internal use:
-```bash
-# Configure private registry
-npm config set registry https://your-private-registry.com
-
-# Or publish to specific registry
-npm publish --registry https://your-private-registry.com
-```
+- **ZUDELLO_TOKEN** (required): JWT authentication token from your Zudello account
+- **ZUDELLO_ORGANIZATION** (required): Your organization UUID
+- **ZUDELLO_TEAM** (required): Your team UUID
+- **ZUDELLO_CLUSTER_URL** (optional): Region-specific API cluster (default: api.1.eur1.zudello.io)
+- **AUTHENTICATION_API_BASE** (optional): Organization-level API endpoint (default: api.1.global.zudello.io)
+- **LOG_LEVEL** (optional): Logging level - debug, info, warn, error (default: info)
 
 ### API Endpoints
 
 The MCP server uses two different API endpoints:
 
-1. **Team-Level API** (`ZUDELLO_CLUSTER_URL`): Used for most operations (106 tools)
-   - Default: `api.1.eur1.zudello.io`
+1. **Team-Level API** (`ZUDELLO_CLUSTER_URL`): Used for most operations (97 tools)
    - Region-specific endpoints for team data and operations
-   - Examples: EUR1, US1, APAC1 clusters
+   - Examples: `api.1.eur1.zudello.io`, `api.au.3.zudello.io`, `api.us.1.zudello.io`
 
 2. **Organization-Level API** (`AUTHENTICATION_API_BASE`): Used for org admin operations (9 tools)
-   - Default: `api.1.global.zudello.io` (https:// is added automatically)
-   - Global endpoint for cross-team operations
-   - Used by: Teams, Users, and Groups management tools
-   - Override if your org uses a custom authentication service
-   - **Note**: Only provide the domain, protocol is added automatically
+   - Default: `api.1.global.zudello.io`
+   - Global endpoint for cross-team operations (teams, users, groups)
 
 ## Tool Categories (106 Total)
 
@@ -452,9 +163,6 @@ The MCP server uses two different API endpoints:
 - Read: `zudelloGetSentence`, `zudelloGetSentenceTemplate`, `zudelloListSentences`, `zudelloListSentenceTemplates`, `zudelloListSentenceResources`
 - Write: `zudelloCreateSentence`, `zudelloUpdateSentence`, `zudelloUpdateSentencesOrder`
 
-### History (1 tool)
-- `zudelloGetHistory` - View audit trail and change history
-
 ### Automation System (10 tools)
 - Scripts: `zudelloGetScript`, `zudelloListScripts`, `zudelloListGlobalIntegrations`, `zudelloListGlobalScriptsForIntegration`
 - Triggers: `zudelloGetTrigger`, `zudelloListTriggers`
@@ -467,196 +175,91 @@ The MCP server uses two different API endpoints:
 - `zudelloListAvailableIntegrations` - List available integrations
 - `zudelloGetConnectionTemplate` - Get connection template
 
-### Trigger & Sync Control (2 tools)
-- `zudelloSetTriggerEnabled` - Enable/disable triggers (high-risk)
-- `zudelloInitiateSync` - Trigger data sync (high-risk)
-
-### Bulk Operations (2 tools)
-- `zudelloBulkApproveMilestones` - Approve multiple items
-- `zudelloBulkSendReminders` - Send approval reminders
-
-### Approval Workflows (1 tool)
-- `zudelloGetApprovalFlows` - View approval workflow configurations
-
-### Users & Groups (2 tools)
-- `zudelloGetUserGroups` - Get user groups
-- `zudelloGetUsers` - Get team users
-
-### Datasets (4 tools)
-- Read: `zudelloListDatasets`, `zudelloGetDataset`
-- Write: `zudelloCreateDataset`, `zudelloUpdateDataset`
-
-### Field Settings (4 tools)
-- Read: `zudelloListFields`, `zudelloGetField`
-- Write: `zudelloCreateField`, `zudelloUpdateField`
-
-### Quick Actions (5 tools)
-- Read: `zudelloListQuickActions`, `zudelloGetQuickAction`
-- Write: `zudelloCreateQuickAction`, `zudelloUpdateQuickAction`, `zudelloTriggerQuickAction`
-
-### Export Templates (7 tools)
-- Read: `zudelloListExportTemplates`, `zudelloGetExportTemplate`, `zudelloListExports`, `zudelloGetExportDownloadUrl`
-- Write: `zudelloCreateExportTemplate`, `zudelloUpdateExportTemplate`, `zudelloRunExport`
-
-### Document Types (5 tools)
-- Read: `zudelloListDocumentTypes`, `zudelloGetDocumentType`, `zudelloGetMergedFormMetadata`
-- Write: `zudelloCreateDocumentType`, `zudelloUpdateDocumentType`
-
-### Organization Admin (9 tools)
-- Teams: `zudelloListOrgTeams`, `zudelloFetchOrgTeam`, `zudelloUpdateOrgTeam`
-- Users: `zudelloListOrgUsers`, `zudelloFetchOrgUser`, `zudelloCreateOrgUser`, `zudelloUpdateOrgUser`, `zudelloAssignUserToTeam`
-- Groups: `zudelloListOrgUserGroups`
-
-### Notifications (3 tools)
-- `zudelloListNotificationTypes` - List notification types
-- `zudelloGetNotificationPreferences` - Get user preferences
-- `zudelloUpdateNotificationPreferences` - Update preferences
-
-### Exception Reasons (6 tools)
-- Budget: `zudelloListBudgetExceptionReasons`, `zudelloCreateBudgetExceptionReason`, `zudelloUpdateBudgetExceptionReason`
-- Contract: `zudelloListContractExceptionReasons`, `zudelloCreateContractExceptionReason`, `zudelloUpdateContractExceptionReason`
+### Additional Categories
+- **Trigger & Sync Control** (2 tools) - Enable/disable triggers, initiate syncs
+- **Bulk Operations** (2 tools) - Bulk approve milestones, send reminders
+- **Approval Workflows** (1 tool) - View approval configurations
+- **Users & Groups** (2 tools) - Get users and user groups
+- **Admin Tools** (13 tools) - Datasets, fields, quick actions
+- **Documents** (12 tools) - Export templates, document types
+- **Organization Admin** (9 tools) - Teams, users, groups management
+- **Notifications** (3 tools) - Notification preferences
+- **Exception Reasons** (6 tools) - Budget and contract exceptions
+- **Language** (2 tools) - Custom terminology management
+- **Document Context** (2 tools) - Budget and contract validation
+- **Inbox Management** (8 tools) - Email inbox configuration
+- **Document Statuses** (5 tools) - Status management
+- **History** (1 tool) - Audit trail access
+
+For a complete catalog of all 106 tools with detailed descriptions and parameters, see [TOOL_CATALOG.md](./TOOL_CATALOG.md).
 
-### Language Placeholders (2 tools)
-- `zudelloGetLanguagePlaceholders` - Get custom terminology labels
-- `zudelloUpdateLanguagePlaceholders` - Update terminology
-
-### Inbox Management (8 tools)
-- Domain: `zudelloGetInboundDomain`
-- Inboxes: `zudelloListInboxes`, `zudelloFetchInbox`, `zudelloCreateInbox`, `zudelloUpdateInbox`
-- Templates: `zudelloListInboxTemplates`, `zudelloCreateInboxTemplate`, `zudelloUpdateInboxTemplate`
-
-### Document Context (2 tools)
-- `zudelloCheckDocumentBudgets` - Validate document against budgets
-- `zudelloCheckContractPricing` - Check contract pricing compliance
-
-### Document Statuses (5 tools)
-- Read: `zudelloListStatuses`, `zudelloGetStatus`
-- Write: `zudelloCreateStatus`, `zudelloUpdateStatus`, `zudelloReorderStatuses`
-
-## Development
+## Tool Approval Metadata
 
-```bash
-# Development mode with auto-reload
-npm run dev
+Write tools (41 total) return approval metadata with risk levels:
 
-# Type check
-npm run typecheck
+### High Risk (11 tools)
+Operations that can significantly impact system behavior or data:
+- Trigger/sync control, critical updates, org user creation
 
-# Build
-npm run build
-```
+### Medium Risk (24 tools)
+Creation operations and bulk actions:
+- Creating resources, bulk operations, org admin tasks
 
-## Architecture
+### Low Risk (6 tools)
+Safe operations with minimal impact:
+- Reorder operations, notification preferences, exports
 
-```
-app-mcp/
-├── src/
-│   ├── index.ts              # MCP server entry point
-│   ├── context/
-│   │   └── auth.ts           # Multi-tenant authentication
-│   ├── tools/                # 106 tool implementations
-│   │   ├── core/             # Core operations (3)
-│   │   ├── models/           # Model discovery (5)
-│   │   ├── config/           # Configuration (5)
-│   │   ├── resources/        # Resource operations (2)
-│   │   ├── sentences/        # Automation rules (8)
-│   │   ├── history/          # History (1)
-│   │   ├── automation/       # Automation system (10)
-│   │   ├── connections/      # Connections (5)
-│   │   ├── control/          # Trigger/sync control (2)
-│   │   ├── bulk/             # Bulk operations (2)
-│   │   ├── approvals/        # Approval workflows (1)
-│   │   ├── users/            # Users & groups (2)
-│   │   ├── admin/            # Datasets, fields, quick actions (13)
-│   │   ├── documents/        # Export templates, document types (12)
-│   │   ├── org-admin/        # Organization admin (9)
-│   │   ├── notifications/    # Notifications (3)
-│   │   ├── exceptions/       # Exception reasons (6)
-│   │   ├── language/         # Language placeholders (2)
-│   │   ├── document-context/ # Document validation (2)
-│   │   ├── inboxes/          # Inbox management (8)
-│   │   └── statuses/         # Document statuses (5)
-│   ├── services/
-│   │   └── zudello/          # Zudello API service layer
-│   │       ├── core.ts       # Auth and base request building
-│   │       ├── resources.ts  # Resource CRUD
-│   │       ├── automation.ts # Automation operations
-│   │       ├── sentences.ts  # Sentence operations
-│   │       ├── documents.ts  # Document operations
-│   │       ├── organization.ts # Org admin operations
-│   │       ├── notifications.ts
-│   │       ├── language.ts
-│   │       ├── document-context.ts
-│   │       ├── inboxes.ts
-│   │       └── types.ts      # Service type definitions
-│   ├── constants/
-│   │   └── zudello.ts        # Zudello constants (1807 lines)
-│   ├── utils/
-│   │   └── logger.ts         # Structured logging
-│   └── types/
-│       └── index.ts          # TypeScript type definitions
-└── dist/                     # Compiled JavaScript (ESM)
+Approval metadata structure:
+```typescript
+{
+  requiresApproval: boolean,
+  operation: string,
+  riskLevel: "low" | "medium" | "high",
+  reason: string,
+  affectedResources?: string[],
+  pendingAction?: any
+}
 ```
 
-## Tool Approval Metadata
+## Troubleshooting
 
-Write tools (41 total) return approval metadata with risk levels:
+### "Server not found" or "Connection failed"
+- Verify npx is available: `npx --version`
+- Check your internet connection (npx may need to download the package)
+- Try global installation: `npm install -g @zudello/modelcontextprotocol`
 
-### High Risk (11 tools)
-- Trigger/sync control (2): `zudelloSetTriggerEnabled`, `zudelloInitiateSync`
-- Config/resources (2): `zudelloUpdateConfig`, `zudelloUpdateOrCreateResources`
-- Automation (1): `zudelloUpdateSentence`
-- Datasets/fields (2): `zudelloUpdateDataset`, `zudelloUpdateField`
-- Quick actions (2): `zudelloUpdateQuickAction`, `zudelloTriggerQuickAction`
-- Document types (1): `zudelloUpdateDocumentType`
-- Org admin (1): `zudelloCreateOrgUser`
-
-### Medium Risk (24 tools)
-- Configuration (1): `zudelloCreateConfig`
-- Automation (1): `zudelloCreateSentence`
-- Bulk operations (2): `zudelloBulkApproveMilestones`, `zudelloBulkSendReminders`
-- Admin tools (6): Create/update datasets, fields, statuses, quick actions, export templates, document types
-- Org admin (2): `zudelloUpdateOrgUser`, `zudelloUpdateOrgTeam`
-- Exception reasons (4): Create/update budget and contract exceptions
-- Language (1): `zudelloUpdateLanguagePlaceholders`
-- Inboxes (4): Create/update inboxes and templates
-- Document types (1): `zudelloCreateDocumentType`
-- Statuses (2): `zudelloCreateStatus`, `zudelloUpdateStatus`
+### "Invalid credentials" or authentication errors
+- Verify your ZUDELLO_TOKEN starts with "eyJ"
+- Check ORGANIZATION and TEAM UUIDs are correct format
+- Confirm CLUSTER_URL matches your Zudello instance region
 
-### Low Risk (6 tools)
-- Reorder operations (3): Configs, sentences, statuses
-- Notifications (1): `zudelloUpdateNotificationPreferences`
-- Push message (1): `zudelloPushMessage`
-- Export (1): `zudelloRunExport`
+### Changes not taking effect
+- Always restart Claude Desktop/Code after config changes
+- Verify the config file is in the correct location
+- Check for JSON syntax errors in your config file
 
-## Migration from inapp-chat
+### Enable debug logging
+Set `LOG_LEVEL=debug` in your environment variables to see detailed logs.
 
-This MCP server is a complete migration of all 106 Zudello tools from the inapp-chat Next.js application. Key changes:
+## Documentation
 
-1. **Tool Format**: Migrated from AI SDK format to MCP format
-2. **Authentication**: Changed from Next.js context to explicit AuthContext parameter
-3. **Approval Pattern**: Converted from AI SDK `needsApproval` to MCP `requiresApproval` with `approvalMetadata`
-4. **Service Layer**: Modified to accept AuthContext as first parameter
-5. **Module System**: Converted to ESM with `.js` extensions in imports
+- [Tool Catalog](./TOOL_CATALOG.md) - Complete reference of all 106 tools
+- [Development Guide](./DEVELOPMENT.md) - For contributors and local development
+- [Publishing Guide](./PUBLISHING.md) - For package maintainers
 
-## Testing
+## Development
 
-The MCP server can be tested by:
-1. Running `npm run build` to ensure all tools compile
-2. Configuring Claude Desktop with the server
-3. Testing tool calls through Claude Desktop
+See [DEVELOPMENT.md](./DEVELOPMENT.md) for instructions on:
+- Cloning and building from source
+- Development workflow
+- Running locally
+- Contributing
 
 ## Publishing
 
 This package is automatically published to npm when code is pushed to the `main` branch via GitHub Actions.
 
-For detailed information about:
-- Setting up npm authentication
-- Version management
-- Manual publishing
-- Troubleshooting
-
-See [PUBLISHING.md](./PUBLISHING.md)
+For manual publishing instructions, see [PUBLISHING.md](./PUBLISHING.md).
 
 ## License