@bheemverse/erp-mcp 1.0.0

package/ERP_AGENT_DEVELOPER_GUIDE.md

@@ -0,0 +1,649 @@
+# Bheem Core ERP — Agent Developer Guide
+
+> Build, register, deploy, and customize AI agents for the Bheem ERP system.
+
+---
+
+## Architecture
+
+```
+erp.agentbheem.com (FastAPI, port 8000)
+┌─────────────────────────────────────────────┐
+│  HR, Accounting, CRM, Sales, Projects,      │
+│  Inventory, Purchase                        │
+│  200+ REST API endpoints                    │
+│  Multi-tenant (company_id)                  │
+└─────────────────────────────────────────────┘
+           ▲                          ▲
+           │ REST calls               │ Template registration
+┌──────────────────────┐    ┌──────────────────────┐
+│  erp-mcp             │───►│  Orchestrator        │
+│  (port 9013)         │    │  (port 8009)         │
+│  5 MCP tools         │    │  Runs agents         │
+│  6 agent templates   │    │  DO NOT MODIFY       │
+│  YOU BUILD THIS      │    └──────────────────────┘
+└──────────────────────┘
+```
+
+**What you work on:**
+- `packages/@bheem/erp-mcp/` — MCP tools and agent templates
+- `modules/bheem-core/` — ERP backend (FastAPI)
+
+**What you do NOT touch:**
+- `orchestrator` — Agent execution engine (port 8009). Protected, platform team only.
+
+### SDK & Package
+
+| Resource | URL |
+|----------|-----|
+| **MCP SDK (starter template)** | `git clone https://github.com/Bheem-Platform/bheem-mcp-sdk.git` |
+| **MCP Server Core (npm)** | `npm install @bheemverse/mcp-server-core` |
+| **Full SDK Developer Guide** | `DEVELOPER_GUIDE.md` inside the SDK repo |
+
+---
+
+## Table of Contents
+
+1. [ERP Module Overview](#1-erp-module-overview)
+2. [Available Agents](#2-available-agents)
+3. [MCP Tools Reference](#3-mcp-tools-reference)
+4. [Creating New Agents](#4-creating-new-agents)
+5. [Customizing Existing Agents](#5-customizing-existing-agents)
+6. [Template Config Reference](#6-template-config-reference)
+7. [Authentication & Multi-Tenancy](#7-authentication--multi-tenancy)
+8. [Build & Deploy](#8-build--deploy)
+9. [Testing](#9-testing)
+10. [Possible Agent Ideas](#10-possible-agent-ideas)
+11. [Troubleshooting](#11-troubleshooting)
+
+---
+
+## 1. ERP Module Overview
+
+Bheem Core ERP has 7 modules with 200+ API endpoints:
+
+| Module | API Base | Key Entities |
+|--------|----------|-------------|
+| **HR** | `/api/hr/` | Employees, departments, attendance, leave, payroll, recruitment, expenses |
+| **Accounting** | `/api/accounting/` | Chart of accounts, journal entries, invoices, budgets, fiscal years, reports, fixed assets |
+| **CRM** | `/api/crm/` | Contacts, accounts, opportunities, leads, activities, campaigns, support tickets |
+| **Sales** | `/api/sales/` | Customers, vendors, quotes, orders, invoices, payments |
+| **Inventory** | `/api/inventory/` | Warehouses, stock levels, stock movements, adjustments |
+| **Project Management** | `/project-management/api/v1/` | Projects, tasks, milestones, team members, time logs, budget, risks, documents |
+| **Purchase** | `/api/purchase/` | Purchase orders, vendor bills (extend via new MCP tool) |
+
+**Tech Stack:** FastAPI + SQLAlchemy async + PostgreSQL (multi-schema) + Redis event bus
+**Production:** `https://erp.agentbheem.com` (server `37.27.89.140`)
+
+---
+
+## 2. Available Agents
+
+### erp-hr-agent — HR Manager
+**20 actions** covering the full HR lifecycle.
+
+| Action | Params | Permission |
+|--------|--------|-----------|
+| `dashboard` | — | read |
+| `list_employees` | `department_id?, status?, limit?` | read |
+| `get_employee` | `employee_id` | read |
+| `create_employee` | `first_name, last_name, email, department_id, position?` | write |
+| `update_employee` | `employee_id, ...fields` | write |
+| `list_departments` | — | read |
+| `create_department` | `name, parent_id?` | admin |
+| `list_attendance` | `employee_id?, date_from?, date_to?, limit?` | read |
+| `mark_attendance` | `employee_id, date, check_in, check_out?` | write |
+| `list_leave_requests` | `employee_id?, status?, limit?` | read |
+| `create_leave_request` | `employee_id, leave_type, start_date, end_date, reason?` | write |
+| `approve_leave` | `leave_request_id, status, remarks?` | admin |
+| `list_candidates` | `status?, limit?` | read |
+| `create_candidate` | `first_name, last_name, email, position, resume_url?` | write |
+| `list_payroll_runs` | `month?, year?, limit?` | read |
+| `get_payslip` | `payslip_id` | read |
+| `run_payroll` | `month, year, department_id?` | admin |
+| `list_expenses` | `employee_id?, status?, limit?` | read |
+| `create_expense` | `employee_id, amount, category, description, receipt_url?` | write |
+| `approve_expense` | `expense_id, status, remarks?` | admin |
+
+### erp-accounting-agent — Accounting Manager
+**17 actions** for financial management.
+
+| Action | Params | Permission |
+|--------|--------|-----------|
+| `dashboard` | — | read |
+| `list_accounts` | `account_type?, limit?` | read |
+| `get_account` | `account_id` | read |
+| `create_account` | `name, account_type, code, parent_id?` | write |
+| `list_journal_entries` | `date_from?, date_to?, status?, limit?` | read |
+| `create_journal_entry` | `date, description, lines[{account_id, debit, credit}]` | write |
+| `list_invoices` | `status?, customer_id?, date_from?, date_to?, limit?` | read |
+| `get_invoice` | `invoice_id` | read |
+| `create_invoice` | `customer_id, due_date, lines[{description, quantity, unit_price}]` | write |
+| `list_budgets` | `fiscal_year?, limit?` | read |
+| `create_budget` | `name, fiscal_year_id, lines[{account_id, amount}]` | admin |
+| `list_fiscal_years` | — | read |
+| `financial_report` | `report_type, date_from, date_to` | read |
+| `list_cost_centers` | — | read |
+| `list_profit_centers` | — | read |
+| `list_fixed_assets` | `status?, limit?` | read |
+| `ar_ap_summary` | — | read |
+
+**Report types:** `trial_balance`, `income_statement`, `balance_sheet`
+
+### erp-crm-agent — CRM Manager
+**22 actions** for customer relationship management.
+
+| Action | Params | Permission |
+|--------|--------|-----------|
+| `analytics` | — | read |
+| `list_contacts` | `limit?` | read |
+| `get_contact` | `contact_id` | read |
+| `create_contact` | `first_name, last_name, email?, phone?, company?` | write |
+| `list_accounts` | `limit?` | read |
+| `get_account` | `account_id` | read |
+| `create_account` | `name, industry?, website?` | write |
+| `list_opportunities` | `stage?, owner_id?, limit?` | read |
+| `get_opportunity` | `opportunity_id` | read |
+| `create_opportunity` | `name, account_id, stage, value?, close_date?` | write |
+| `update_opportunity` | `opportunity_id, stage?, value?, close_date?` | write |
+| `list_leads` | `status?, source?, limit?` | read |
+| `get_lead` | `lead_id` | read |
+| `create_lead` | `name, email?, phone?, source?, campaign_id?` | write |
+| `update_lead` | `lead_id, status?, assigned_to?` | write |
+| `list_activities` | `contact_id?, type?, limit?` | read |
+| `create_activity` | `type[call|email|meeting|note], contact_id?, subject, description?` | write |
+| `list_campaigns` | `status?, limit?` | read |
+| `create_campaign` | `name, type, start_date?, end_date?, budget?` | write |
+| `list_tickets` | `status?, priority?, limit?` | read |
+| `create_ticket` | `subject, description, contact_id?, priority?` | write |
+| `update_ticket` | `ticket_id, status?, priority?, assigned_to?` | write |
+
+### erp-sales-agent — Sales & Inventory Manager
+**20 actions** for the full sales cycle + inventory.
+
+| Action | Params | Permission |
+|--------|--------|-----------|
+| `dashboard` | — | read |
+| `list_customers` | `limit?` | read |
+| `get_customer` | `customer_id` | read |
+| `create_customer` | `name, email?, phone?, company?` | write |
+| `list_vendors` | `limit?` | read |
+| `create_vendor` | `name, email?, phone?` | write |
+| `list_quotes` | `status?, customer_id?, limit?` | read |
+| `get_quote` | `quote_id` | read |
+| `create_quote` | `customer_id, items[{sku_id, quantity, unit_price}], valid_until?` | write |
+| `list_orders` | `status?, customer_id?, limit?` | read |
+| `get_order` | `order_id` | read |
+| `create_order` | `customer_id, items[{sku_id, quantity, unit_price}]` | write |
+| `list_invoices` | `status?, customer_id?, limit?` | read |
+| `create_invoice` | `order_id` | write |
+| `record_payment` | `invoice_id, amount, payment_method, reference?` | write |
+| `list_warehouses` | — | read |
+| `get_stock_levels` | `warehouse_id?, sku_id?, limit?` | read |
+| `list_stock_movements` | `warehouse_id?, sku_id?, limit?` | read |
+| `create_stock_movement` | `sku_id, warehouse_id, quantity, movement_type[in|out|transfer], reason?` | write |
+| `adjust_inventory` | `warehouse_id, sku_id, new_quantity, reason` | admin |
+
+**Sales Cycle:** Customer → Quote → Order → Invoice → Payment
+
+### erp-projects-agent — Project Manager
+**21 actions** for project management.
+
+| Action | Params | Permission |
+|--------|--------|-----------|
+| `analytics` | — | read |
+| `list_projects` | `status?, limit?` | read |
+| `get_project` | `project_id` | read |
+| `create_project` | `name, description?, start_date?, end_date?, budget?` | write |
+| `update_project` | `project_id, ...fields` | write |
+| `list_tasks` | `project_id?, assignee_id?, status?, priority?, limit?` | read |
+| `get_task` | `task_id` | read |
+| `create_task` | `project_id, title, description?, assignee_id?, priority?, due_date?` | write |
+| `update_task` | `task_id, status?, priority?, assignee_id?, due_date?` | write |
+| `list_milestones` | `project_id?, limit?` | read |
+| `create_milestone` | `project_id, name, due_date, description?` | write |
+| `list_team_members` | `project_id` | read |
+| `add_team_member` | `project_id, employee_id, role?` | write |
+| `list_time_logs` | `project_id?, task_id?, employee_id?, date_from?, date_to?, limit?` | read |
+| `log_time` | `task_id, hours, date, description?` | write |
+| `get_budget` | `project_id` | read |
+| `list_comments` | `task_id, limit?` | read |
+| `add_comment` | `task_id, content` | write |
+| `list_documents` | `project_id, limit?` | read |
+| `list_risks` | `project_id, limit?` | read |
+| `create_risk` | `project_id, title, description?, probability?, impact?` | write |
+
+### erp-router — ERP Assistant
+Routes user queries to the right specialist agent. Understands natural language:
+- "Show me employee list" → erp-hr-agent
+- "What's our AR/AP status?" → erp-accounting-agent
+- "Update lead status" → erp-crm-agent
+- "Create a sales order" → erp-sales-agent
+- "How's the project going?" → erp-projects-agent
+
+---
+
+## 3. MCP Tools Reference
+
+The ERP MCP server exposes 5 domain tools. Each tool uses action routing — one tool handles many operations via the `action` field.
+
+### Tool: `hr`
+```json
+{
+  "action": "list_employees",
+  "params": { "department_id": "dept-123", "limit": 10 }
+}
+```
+
+### Tool: `accounting`
+```json
+{
+  "action": "financial_report",
+  "params": { "report_type": "income_statement", "date_from": "2026-01-01", "date_to": "2026-01-31" }
+}
+```
+
+### Tool: `crm`
+```json
+{
+  "action": "create_lead",
+  "params": { "name": "John Doe", "email": "john@example.com", "source": "website" }
+}
+```
+
+### Tool: `sales`
+```json
+{
+  "action": "create_order",
+  "params": { "customer_id": "cust-456", "items": [{"sku_id": "SKU-001", "quantity": 5, "unit_price": 100}] }
+}
+```
+
+### Tool: `projects`
+```json
+{
+  "action": "create_task",
+  "params": { "project_id": "proj-789", "title": "Design review", "priority": "high", "due_date": "2026-03-01" }
+}
+```
+
+---
+
+## 4. Creating New Agents
+
+### Step 1: Add a template to `src/templates/index.ts`
+
+```typescript
+// Add to the erpTemplates array:
+{
+  id: 'erp-payroll-specialist',
+  name: 'Payroll Specialist',
+  version: '1.0.0',
+  description: 'Dedicated payroll agent — runs payroll, generates payslips, tracks expenses',
+  icon: 'credit-card',
+  category: 'hr',
+  executionMode: 'channel',
+  orchestrator: 'sdk',
+  model: 'auto',
+  mcpServers: ERP_MCP,
+  allowedTools: [],
+  maxTurns: 10,
+  maxBudgetUsd: 1.0,
+  tierRequired: 'free',
+  triggers: ['manual', 'schedule', 'channel'],
+  connectedServices: ['erp'],
+  systemPrompt: `You are a payroll specialist for Bheem ERP.
+
+## Tools
+- hr({ action: 'list_payroll_runs', params: { month?, year? } })
+- hr({ action: 'get_payslip', params: { payslip_id } })
+- hr({ action: 'run_payroll', params: { month, year, department_id? } })
+- hr({ action: 'list_expenses', params: { employee_id?, status? } })
+- hr({ action: 'approve_expense', params: { expense_id, status, remarks? } })
+- hr({ action: 'list_employees', params: { department_id? } })
+
+## Workflow
+1. Check existing payroll runs for the period
+2. List employees in target department
+3. Run payroll (requires admin access)
+4. Review generated payslips
+5. Handle pending expenses
+
+NEVER use curl or raw HTTP calls — use MCP tools only.
+${COMMUNICATION_STYLE}`,
+}
+```
+
+### Step 2: Build and restart
+
+```bash
+cd packages/@bheem/erp-mcp
+npm run build
+pm2 restart erp-mcp
+```
+
+Templates self-register with the orchestrator on boot. No orchestrator changes needed.
+
+### Step 3: Add a new MCP tool (if needed)
+
+Create `src/tools/purchase.ts`:
+```typescript
+import type { McpToolDefinition } from '@bheem/mcp-server-core';
+import { erpClient } from '../utils/erp-client.js';
+import { getUserScope, authHeaders } from '../utils/scope.js';
+
+export const purchaseTools: McpToolDefinition[] = [
+  {
+    name: 'purchase',
+    description: `Purchase operations. Available actions:
+- list_purchase_orders: List POs (params: status?, vendor_id?, limit?)
+- create_purchase_order: Create PO (params: vendor_id, items[{sku_id, quantity, unit_price}])
+- list_vendor_bills: List vendor bills (params: status?, limit?)`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list_purchase_orders', 'create_purchase_order', 'list_vendor_bills'],
+        },
+        params: { type: 'object' },
+      },
+      required: ['action'],
+    },
+    execute: async (input, context) => {
+      const scope = getUserScope(context);
+      const p = (input.params || {}) as Record<string, any>;
+      const headers = authHeaders(scope);
+
+      if (scope.role === 'visitor') return { error: 'Please log in.' };
+
+      try {
+        switch (input.action) {
+          case 'list_purchase_orders':
+            return (await erpClient.get('/api/purchase/orders/', {
+              params: { status: p.status, vendor_id: p.vendor_id, limit: p.limit ?? 50 },
+              headers,
+            })).data;
+          case 'create_purchase_order': {
+            if (!scope.canWrite) return { error: 'Write access required.' };
+            return (await erpClient.post('/api/purchase/orders/', p, { headers })).data;
+          }
+          case 'list_vendor_bills':
+            return (await erpClient.get('/api/purchase/vendor-bills/', {
+              params: { status: p.status, limit: p.limit ?? 50 },
+              headers,
+            })).data;
+          default:
+            return { error: `Unknown action: ${input.action}` };
+        }
+      } catch (error: any) {
+        return { error: `Purchase ${input.action} failed`, details: error.response?.data?.detail || error.message };
+      }
+    },
+  },
+];
+```
+
+Then add it to `src/index.ts`:
+```typescript
+import { purchaseTools } from './tools/purchase.js';
+// ... in tools array:
+...purchaseTools,
+```
+
+---
+
+## 5. Customizing Existing Agents
+
+### Change the system prompt
+Edit the agent's `systemPrompt` in `src/templates/index.ts`. The prompt controls:
+- Which tools the agent knows about
+- Workflow steps
+- Communication style
+- Permission awareness
+
+### Limit tool access
+Use `allowedTools` to restrict which MCP tools an agent can call:
+```typescript
+allowedTools: ['mcp__erp__hr', 'mcp__erp__accounting'],  // Only HR + accounting
+```
+
+### Add subagents
+For complex multi-step workflows, add subagents:
+```typescript
+subagents: {
+  'data-gatherer': {
+    description: 'Collects financial data from multiple sources.',
+    tools: ['mcp__erp__*'],
+    prompt: 'Gather accounting data: dashboard, AR/AP summary, recent journal entries.',
+    model: 'haiku',
+  },
+  'report-writer': {
+    description: 'Writes executive summaries from collected data.',
+    tools: ['mcp__erp__*'],
+    prompt: 'Analyze financial data and write a concise executive summary.',
+    model: 'sonnet',
+  },
+},
+```
+
+---
+
+## 6. Template Config Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Unique template ID (prefix with `erp-`) |
+| `name` | string | yes | Display name |
+| `version` | string | yes | Semver version |
+| `description` | string | yes | Short description for UI |
+| `icon` | string | no | Lucide icon name |
+| `category` | string | no | `hr`, `finance`, `sales`, `projects`, `general` |
+| `executionMode` | string | yes | `channel` (chat), `sandbox` (code exec), `client` (container) |
+| `orchestrator` | string | yes | `sdk` (recommended) |
+| `model` | string | yes | `auto`, `sonnet`, `haiku`, `opus` |
+| `mcpServers` | object | yes | MCP server connections |
+| `allowedTools` | string[] | yes | Tool filter (empty = all) |
+| `maxTurns` | number | yes | Max agent turns per conversation |
+| `maxBudgetUsd` | number | yes | Max spend per conversation |
+| `tierRequired` | string | yes | `free`, `pro`, `enterprise` |
+| `triggers` | string[] | yes | `manual`, `webhook`, `schedule`, `channel` |
+| `connectedServices` | string[] | no | Service dependencies |
+| `systemPrompt` | string | yes | Agent instructions |
+| `skills` | string[] | no | Platform skills to inject (omit = all skills) |
+| `subagents` | object | no | Sub-agent definitions for complex workflows |
+| `pevConfig` | object | no | Plan-Execute-Verify config for advanced agents |
+
+---
+
+## 7. Authentication & Multi-Tenancy
+
+### How auth works
+The ERP uses JWT tokens via Bheem Passport. The MCP server extracts user context from the orchestrator's claims:
+
+```typescript
+// src/utils/scope.ts
+export function getUserScope(context: any) {
+  const claims = context?.claims || {};
+  return {
+    userId: claims.user_id,
+    companyId: claims.company_id,       // Multi-tenant scoping
+    role: claims.role || 'visitor',
+    token: claims.access_token,
+    canWrite: ['admin', 'manager', 'editor', 'SuperAdmin'].includes(claims.role),
+    canAccessAll: ['admin', 'SuperAdmin'].includes(claims.role),
+  };
+}
+```
+
+### Permission levels
+| Level | Roles | Can Do |
+|-------|-------|--------|
+| **Read** | Any authenticated user | List, get, dashboards, reports |
+| **Write** | admin, manager, editor, SuperAdmin | Create, update |
+| **Admin** | admin, SuperAdmin | Approve leave/expenses, run payroll, create departments, adjust inventory, create budgets |
+
+### Multi-tenancy
+All API calls include `company_id` from the JWT. The ERP backend scopes data automatically — agents only see data for their company.
+
+---
+
+## 8. Build & Deploy
+
+### First time setup
+```bash
+cd packages/@bheem/erp-mcp
+npm install
+npm run build
+pm2 start dist/index.js --name erp-mcp \
+  --env ERP_MCP_PORT=9013 \
+  --env ORCHESTRATOR_URL=http://localhost:8009 \
+  --env ERP_API_URL=https://erp.agentbheem.com
+pm2 save
+```
+
+### After changes
+```bash
+cd packages/@bheem/erp-mcp
+npm run build && pm2 restart erp-mcp
+```
+
+### Verify
+```bash
+# Health check
+curl http://localhost:9013/health
+
+# Verify templates registered
+curl http://localhost:8009/api/v1/templates | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+erp = [t['id'] for t in data['templates'] if t['id'].startswith('erp')]
+print(f'{len(erp)} ERP templates:', erp)
+"
+```
+
+### Environment variables
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ERP_MCP_PORT` | `9013` | MCP server port |
+| `ERP_MCP_AUTH_TOKEN` | — | Optional auth token |
+| `ERP_MCP_EXTERNAL_URL` | `http://localhost:9013/mcp` | URL for agent access |
+| `ERP_API_URL` | `https://erp.agentbheem.com` | ERP backend URL |
+| `ORCHESTRATOR_URL` | `http://localhost:8009` | Orchestrator for template registration |
+
+---
+
+## 9. Testing
+
+### Test a tool directly
+```bash
+curl -X POST http://localhost:9013/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+      "name": "hr",
+      "arguments": {
+        "action": "dashboard"
+      }
+    }
+  }'
+```
+
+### Test via orchestrator
+```bash
+curl -X POST http://localhost:8009/api/v1/messages \
+  -H "Content-Type: application/json" \
+  -d '{
+    "templateId": "erp-hr-agent",
+    "messages": [{"role": "user", "content": "Show me the employee list"}],
+    "claims": {"user_id": "test", "role": "admin", "company_id": "1"}
+  }'
+```
+
+---
+
+## 10. Possible Agent Ideas
+
+Here are agents you can build using the existing tools (or by adding new ones):
+
+### Cross-Module Agents
+
+| Agent | Description | Tools Used |
+|-------|-------------|-----------|
+| **Financial Controller** | Monthly close: verify journal entries, reconcile AR/AP, generate reports | `accounting`, `sales` |
+| **Workforce Planner** | Match project staffing with HR data, identify capacity gaps | `hr`, `projects` |
+| **Sales-to-Project Converter** | When a sales order is won, auto-create a project with tasks | `sales`, `projects` |
+| **Expense Auditor** | Review employee expenses against project budgets | `hr`, `projects` |
+| **Customer 360** | Unified view: CRM contact + sales history + support tickets | `crm`, `sales` |
+
+### Specialized Agents
+
+| Agent | Description | Tools Used |
+|-------|-------------|-----------|
+| **Payroll Specialist** | Run payroll, generate payslips, handle expense approvals | `hr` |
+| **Recruitment Assistant** | Track candidates, schedule interviews, manage offers | `hr` |
+| **Leave Manager** | Handle leave requests, check balances, approve/reject | `hr` |
+| **Invoice Collector** | Track overdue invoices, send reminders, record payments | `accounting`, `sales` |
+| **Budget Watchdog** | Alert on budget overruns across projects and departments | `accounting`, `projects` |
+| **Inventory Optimizer** | Track stock levels, predict reorder points, suggest movements | `sales` (inventory) |
+| **Pipeline Coach** | Analyze CRM pipeline, suggest next actions for stale deals | `crm` |
+| **Campaign ROI Analyzer** | Track campaign spend vs. converted opportunities | `crm` |
+| **Time Tracker** | Log time, generate utilization reports, flag overtime | `projects`, `hr` |
+| **Risk Monitor** | Track project risks, escalate high-probability items | `projects` |
+
+### Adding Purchase Module (not yet exposed)
+
+The ERP has a Purchase module (`/api/purchase/`) not yet wrapped as an MCP tool. To add it:
+1. Create `src/tools/purchase.ts` (see [Section 4](#4-creating-new-agents))
+2. Register in `src/index.ts`
+3. Build new agents like **Procurement Manager** or **Vendor Payment Tracker**
+
+---
+
+## 11. Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `Please log in.` | No JWT claims in context | Ensure orchestrator passes claims |
+| `Write access required.` | User role is read-only | User needs admin/manager/editor role |
+| `Admin access required.` | Action requires admin | User needs admin or SuperAdmin role |
+| `Unknown action: X` | Typo in action name | Check the tool's action enum |
+| Templates not appearing | Registration failed on boot | Check `pm2 logs erp-mcp` for errors |
+| `ECONNREFUSED :9013` | MCP server not running | `pm2 restart erp-mcp` |
+| `ERP API timeout` | ERP backend slow/down | Check `https://erp.agentbheem.com/health` |
+| `404 from ERP API` | Wrong endpoint path | Verify against ERP FastAPI docs |
+
+### Useful commands
+```bash
+pm2 logs erp-mcp --lines 50        # View logs
+pm2 restart erp-mcp                 # Restart
+curl http://localhost:9013/health   # Health check
+```
+
+---
+
+## File Structure
+
+```
+packages/@bheem/erp-mcp/
+├── package.json
+├── tsconfig.json
+├── ERP_AGENT_DEVELOPER_GUIDE.md   ← This file
+├── src/
+│   ├── index.ts                    ← Server entry (port 9013)
+│   ├── templates/
+│   │   └── index.ts                ← 6 agent templates
+│   ├── tools/
+│   │   ├── hr.ts                   ← 20 HR actions
+│   │   ├── accounting.ts           ← 17 Accounting actions
+│   │   ├── crm.ts                  ← 22 CRM actions
+│   │   ├── sales.ts                ← 20 Sales + Inventory actions
+│   │   └── projects.ts             ← 21 Project Management actions
+│   └── utils/
+│       ├── erp-client.ts           ← Axios client → erp.agentbheem.com
+│       └── scope.ts                ← Auth + multi-tenancy
+└── dist/                            ← Built output
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }