# Zenkit MCP Server (Raw API)

Direct Zenkit API access for Claude Desktop. Full control via single universal tool.

## Installation

### Option 1: Automated Installation (Recommended)

**Using Node.js:**

```bash
curl -O https://raw.githubusercontent.com/wbgrds/mcp-zenkit/main/install.js
node install.js
```

**Using Bash:**

```bash
bash <(curl -s https://raw.githubusercontent.com/wbgrds/mcp-zenkit/main/install.sh)
```

**In Claude Code:**
1. Open this repo in Claude Code
2. Say: "Run install.js"
3. Provide your Zenkit API key
4. Done!

The installer will:
- Clone the repository
- Install Node dependencies
- Create `.env` with your API key
- Build TypeScript → JavaScript
- Test the MCP server
- Output Claude Desktop configuration

### Option 2: Manual Installation

```bash
# 1. Clone repo
git clone https://github.com/wbgrds/mcp-zenkit.git
cd mcp-zenkit

# 2. Install dependencies
npm install

# 3. Build TypeScript
npm run build

# 4. Create .env with your API key
echo "ZENKIT_API_KEY=your-api-key" > .env
```

### Configure Claude Desktop

Find your configuration file:

**macOS/Linux:**
```
~/.config/Claude/claude_desktop_config.json
```

**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```

Edit or create it with:

```json
{
  "mcpServers": {
    "zenkit": {
      "command": "node",
      "args": ["/path/to/mcp-zenkit/dist/index.js"],
      "env": {
        "ZENKIT_API_KEY": "your-zenkit-api-key"
      }
    }
  }
}
```

Replace `/path/to/mcp-zenkit` with your actual installation path.

**Get your API key:** https://zenkit.com/en/user/profile/developer/

**Restart Claude Desktop** after configuration.

---

## Usage

Single tool: `zenkit(method, path, body)`

### Get Workspaces

```
zenkit('GET', '/workspaces')
```

Response: All workspaces + lists

### Get Lists in Workspace

```
zenkit('GET', '/workspaces/123')
```

### Get List Fields (Elements)

```
zenkit('GET', '/lists/123/elements')
```

Returns: Field names, UUIDs, types, predefined values (for categories)

### List Entries

```
zenkit('POST', '/lists/123/entries', {
  limit: 100,
  skip: 0
})
```

### Create Entry

```
zenkit('POST', '/lists/123/entries', {
  title: "My Task",
  description: "Optional description",
  properties: {
    "field-uuid-1": "value",
    "field-uuid-2": 123,
    "field-uuid-3": ["array", "of", "values"]
  }
})
```

To find field UUIDs: `zenkit('GET', '/lists/123/elements')`

### Update Entry

```
zenkit('PATCH', '/lists/123/entries/entry-uuid', {
  title: "Updated Title",
  properties: {
    "field-uuid": "new-value"
  }
})
```

### Delete Entry

```
zenkit('DELETE', '/lists/123/entries/entry-uuid')
```

---

## Architecture

**Version 2.0 (Approach B: Raw API)**

- One universal tool `zenkit(method, path, body)`
- Direct pass-through to Zenkit API
- No abstraction layer, no hidden logic
- Token-based auth = full account control

**What changed from v1:**
- Removed: `zenkit_create_entry`, `zenkit_update_entry`, `zenkit_get_entries`, etc.
- Added: Single `zenkit` tool for all operations
- Benefit: Works for any Zenkit API endpoint (present + future)

---

## API Reference

Full Zenkit API docs: https://zenkit.com/api/

### Common Endpoints

| Operation | Method | Path | Body |
|-----------|--------|------|------|
| List workspaces | GET | `/workspaces` | — |
| Get workspace | GET | `/workspaces/{id}` | — |
| List entries | POST | `/lists/{id}/entries` | `{limit, skip}` |
| Get fields | GET | `/lists/{id}/elements` | — |
| Create entry | POST | `/lists/{id}/entries` | `{title, properties}` |
| Update entry | PATCH | `/lists/{id}/entries/{uuid}` | `{title, properties}` |
| Delete entry | DELETE | `/lists/{id}/entries/{uuid}` | — |

---

## Examples

### Workflow: Create and Update

```
1. zenkit('GET', '/workspaces')
   → Find workspace ID

2. zenkit('GET', '/lists/123/elements')
   → Find field UUIDs you need

3. zenkit('POST', '/lists/123/entries', {
     title: 'New Task',
     properties: { 'field-uuid': 'value' }
   })
   → Create entry, get entry UUID back

4. zenkit('PATCH', '/lists/123/entries/entry-uuid', {
     title: 'Updated Task'
   })
   → Update the entry
```

### Working with Categories (Dropdowns)

When `predefinedValues` are present in `get_list_fields` response, they are category options:

```json
{
  "name": "Status",
  "uuid": "a1b2c3d4-...",
  "predefinedValues": [
    { "id": 1, "name": "Draft" },
    { "id": 2, "name": "In Progress" },
    { "id": 3, "name": "Done" }
  ]
}
```

Use the `id` value when setting properties:

```
zenkit('POST', '/lists/123/entries', {
  title: 'Task',
  properties: {
    'a1b2c3d4-...': 2  // ← Category ID for "In Progress"
  }
})
```

---

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| "ZENKIT_API_KEY is required" | Environment variable missing | Check `claude_desktop_config.json`, restart Claude |
| "npm: command not found" | Node.js not installed | Install Node.js >= 18 from nodejs.org |
| "Git clone fails" | Git not installed | Install Git |
| "Claude doesn't see tool" | Config not reloaded | Restart Claude Desktop completely |
| "Zenkit API error 404" | Wrong path or resource doesn't exist | Use `zenkit('GET', '/workspaces')` to discover IDs |
| "Field UUID not found" | UUID is incorrect | Get correct UUIDs via `zenkit('GET', '/lists/123/elements')` |

---

## Environment Variables

- `ZENKIT_API_KEY` (required): Zenkit API token
- `ZENKIT_API_BASE` (optional): Override API base URL (default: `https://base.zenkit.com/api/v1`)

---

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run locally (requires ZENKIT_API_KEY env var)
ZENKIT_API_KEY=xxx npm run start
```

---

## License

MIT

## Support

- Zenkit API docs: https://zenkit.com/api/
- Issues: https://github.com/wbgrds/mcp-zenkit/issues

---

## Complete Documentation

- **[README.md](README.md)** – Installation & Quick Start
- **[CHANGELOG.md](CHANGELOG.md)** – Version History & Migration Guide (v1 → v2)
- **[TOOL_REFERENCE.md](TOOL_REFERENCE.md)** – Comprehensive Tool Usage & Examples
- **[Zenkit API Docs](https://zenkit.com/api/)** – Official API Reference