# NocoBase MCP Server v7.0.0

Modern MCP Server for NocoBase CRM using FlowModels API.

## 🚀 Quick Start

### Install & Build
```bash
npm install
npm run build
```

### Configure
Edit `.env`:
```env
NOCOBASE_URL=https://crm.nexpo.vn
NOCOBASE_EMAIL=admin@nocobase.com
NOCOBASE_PASSWORD=admin123
```

### Run
```bash
npm start
```

## 📁 Project Structure

```
src/
├── index.ts              # Main entry point
├── client.ts             # NocoBase HTTP client
├── templates.ts          # UI schema templates
├── tools/                # Tool modules
│   ├── page-tools.ts     # Page & UI operations
│   ├── data-tools.ts     # Bulk data operations
│   ├── relationship-tools.ts  # Relationship management
│   └── workflow-tools.ts # Workflow automation
└── archive/              # V1 legacy (excluded from build)
```

## 🛠️ Available Tools (15)

### Page & UI (8 tools)
- `menu_create_group` - Create menu group
- `page_create` - Create FlowPage
- `page_list` - List all pages
- `page_delete` - Delete page
- `page_inspect` - Inspect page structure
- `table_add` - Add table block
- `column_add` - Add table column
- `action_add` - Add action button

### Collections (2 tools)
- `collection_list` - List all collections
- `collection_get` - Get collection details

### Data CRUD (4 tools)
- `data_list` - Query records
- `data_create` - Create record
- `data_update` - Update record
- `data_delete` - Delete record

### Health (1 tool)
- `health_check` - Check connection

## 📝 Usage Example

```javascript
// 1. Create menu group
menu_create_group({ title: "CRM" })
// Returns: { groupId: "abc123" }

// 2. Create page
page_create({ title: "Leads", parentId: "abc123" })
// Returns: { gridUid: "xyz789", ... }

// 3. Add table
table_add({ gridUid: "xyz789", collection: "leads" })
// Returns: { tableBlockUid: "tbl456", actionsColumnUid: "act789" }

// 4. Add columns
column_add({ tableBlockUid: "tbl456", collection: "leads", fieldPath: "company_name" })
column_add({ tableBlockUid: "tbl456", collection: "leads", fieldPath: "email" })

// 5. Add actions
action_add({ parentUid: "tbl456", actionType: "addNew", collection: "leads" })
action_add({ parentUid: "act789", actionType: "view", collection: "leads", isRowAction: true })
```

## 📚 Documentation

All detailed guides are in the [`docs/`](./docs) folder:

- **[docs/README.md](./docs/README.md)** - Complete guides (bulk ops, relationships, workflows)
- **[docs/ALL_TOOLS.md](./docs/ALL_TOOLS.md)** - All 15 tools reference

For advanced features like bulk operations, relationships, and workflows, see the documentation in `docs/`.

## 🔗 Claude Desktop Integration

### Setup Instructions

1. **Find your Claude Desktop config file:**
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - Linux: `~/.config/Claude/claude_desktop_config.json`

2. **Add NocoBase MCP server to the config:**

```json
{
  "mcpServers": {
    "nocobase": {
      "command": "node",
      "args": ["/Users/travisvo/Projects/nocobase-mcp/dist/index.js"],
      "env": {
        "NOCOBASE_URL": "https://erp.nexpo.vn",
        "NOCOBASE_EMAIL": "your-email@example.com",
        "NOCOBASE_PASSWORD": "your-password"
      }
    }
  }
}
```

3. **Update the path and credentials:**
   - Replace the `args` path with your actual project path
   - Update `NOCOBASE_URL`, `NOCOBASE_EMAIL`, and `NOCOBASE_PASSWORD` with your credentials

4. **Restart Claude Desktop** to load the MCP server

5. **Verify connection:**
   - Open Claude Desktop
   - Look for the 🔌 icon in the bottom right
   - You should see "nocobase" listed with 15 tools available

## 📦 Version History

- **v7.0.0** (2026-01-18) - Refactored structure, removed v2 prefix, organized tools
- **v6.0.0** - V2 FlowPage Edition
- **v5.0.0** - V2 Only
- **v4.x** - Mixed V1/V2 support

## 🗂️ Archive

Legacy V1 files are in `src/archive/` for reference only. They are excluded from compilation and not used in the current version.

## 🔗 Links

- NocoBase: https://www.nocobase.com
- MCP Protocol: https://modelcontextprotocol.io

---

**Version**: 7.0.0  
**Last Updated**: 2026-01-18