npm package: @firestitch/specifymcp
Description: Model Context Protocol (MCP) server for Specify project management platform. Provides tools for managing ERD dataobjects, projects, tasks, plans, and components.
Author: Firestitch
Latest version: 1.0.19

# Specify MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides comprehensive access to the Specify project management platform API. This server enables AI assistants like Claude to interact with Specify projects, ERD diagrams, tasks, plans, components, and more.

## Features

### 🗂️ Project Management
- List and search projects
- Get project details
- Set current project context

### 📊 ERD & Database Design
- **Dataobject Management**: Create, read, update, delete tables and fields
- **Table Operations**: Position tables on ERD diagrams (x1, y1 coordinates)
- **Field Management**: Define data types, primary keys, foreign keys, constraints
- **Relationships**: Establish foreign key relationships between tables

### 📋 Task Management
- Create, update, and search tasks
- Filter by priority, status, assignee
- Add comments to tasks
- Track task assignments and due dates

### 📑 Plan & Component Management
- Manage project plans and versions
- Create and organize components
- Link components to plans and tasks

### 📄 Documentation & Assets
- Manage project documentation
- Handle mockups and design assets
- Search across all content types

### 🔍 Search & Discovery
- Universal search across all entity types
- Enhanced search with multiple strategies
- Filter and pagination support

## Installation

### Option 1: Install from npm (Recommended)

```bash
npm install -g @firestitch/specifymcp
```

### Option 2: Install from source

```bash
git clone https://github.com/firestitch/specifymcp
cd specifymcp
npm install
npm run build
```

## Configuration

### For npm installation (Claude Desktop)

Add to your Claude Desktop configuration file (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "specify": {
      "command": "specify-mcp-server",
      "env": {
        "SPECIFY_ENVIRONMENT": "prod"
      }
    }
  }
}
```

### For source installation

```json
{
  "mcpServers": {
    "specify": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/specify-mcp-server",
      "env": {
        "SPECIFY_ENVIRONMENT": "prod"
      }
    }
  }
}
```

**Note:** Restart Claude Desktop after updating the configuration.

## Available Tools

### Authentication
- `auth` - Authenticate with email and password
- `auth_with_code` - Authenticate with verification code
- `verify_auth` - Check authentication status
- `signout` - Sign out and clear token

### Search
- `search` - Universal search across all entity types

### Projects
- `list_projects` - List/search projects
- `get_project` - Get project details by ID
- `set_current_project` - Set current project context
- `get_current_project` - Get current project context
- `clear_current_project` - Clear project context
- `create_project` - Create new project
- `update_project` - Update existing project
- `delete_project` - Delete project

### Tasks
- `list_tasks` - List/search tasks with filtering
- `get_task` - Get detailed task information
- `create_task` - Create new task
- `update_task` - Update existing task
- `comment_task` - Add comment to task

### Plans & Components
- `list_plans` - List/search project plans
- `get_plan` - Get plan details
- `create_plan` - Create new plan
- `update_plan` - Update existing plan
- `list_components` - List/search components
- `get_component` - Get component details
- `create_component` - Create new component
- `update_component` - Update existing component

### Data & ERDs
- `list_data` - List/search ERD entities
- `get_data` - Get ERD entity details
- `create_data` - Create new ERD entity
- `update_data` - Update ERD entity
- `list_dataobjects` - List tables/fields in ERD
- `get_dataobject` - Get table/field details
- `create_dataobject` - Create table or field
- `update_dataobject` - Update table or field
- `delete_dataobject` - Delete table or field

### Documentation & Mockups
- `list_docs` - List/search documentation
- `get_doc` - Get document details
- `create_doc` - Create new document
- `update_doc` - Update document
- `list_mockups` - List/search mockups/assets
- `get_mockup` - Get mockup details
- `create_mockup` - Create new mockup
- `update_mockup` - Update mockup

### Utilities
- `get_current_account` - Get current user info
- `list_accounts` - List user accounts
- `list_statuses` - Get available statuses for object types
- `list_types` - Get available types for object types
- `relate_objects` - Create relationships between objects
- `get_related_objects` - Get objects related to a specific object
- `list_environments` - List available environments

## Environments

- `prod` - https://fs.specify.com/api/
- `dev` - https://specify.dev.firestitch.com/api/
- `local` - http://specify.local.firestitch.com/api/

## Usage

1. First authenticate with email and password:
   ```bash
   auth --email="your-email@example.com" --password="your-password" --environment="dev"
   ```

2. Set current project context:
   ```bash
   list_projects --limit=10
   set_current_project --projectId=123
   ```

3. Use tools without specifying project:
   ```bash
   list_tasks --assignedToMe=true
   create_task --name="New feature" --priority=30
   ```

### Workflow Examples

**ERD Creation:**
```bash
create_data --name="E-commerce Schema"
create_dataobject --dataId=123 --name="users" --type=table
create_dataobject --dataId=123 --name="user_id" --type=column --parentDataObjectId=456 --dataType=int --key=true
create_dataobject --dataId=123 --name="email" --type=column --parentDataObjectId=456 --dataType=varchar --dataLength=255
```

**Task Management:**
```bash
list_tasks --taskStatus="To Do" --priority=30
update_task --id=789 --taskStatus="In Progress"
comment_task --id=789 --comment="Started working on this"
```

## 📁 Project Structure

```
specifymcp/
├── src/                     # Source code
│   ├── index.ts            # Main MCP server
│   ├── api-client.ts       # Specify API client
│   ├── config.ts           # Configuration
│   └── tools/              # Tool definitions by category
│       ├── auth/           # Authentication tools
│       ├── project/        # Project management tools
│       ├── task/           # Task management tools
│       ├── plan/           # Plan & component tools
│       ├── data/           # ERD & data tools
│       ├── documentation/  # Documentation tools
│       ├── mockups/        # Mockup & asset tools
│       ├── objects/        # Object relationship tools
│       ├── accounts/       # Account management tools
│       ├── environments/   # Environment tools
│       └── utils/          # Utility tools
├── tests/                  # Test suite
│   ├── unit/               # Unit tests
│   ├── integration/        # Integration tests
│   ├── e2e/               # End-to-end tests
│   ├── fixtures/          # Test data
│   └── helpers/           # Test utilities
├── dist/                  # Compiled JavaScript
├── CLAUDE.md              # Project instructions
└── package.json           # Dependencies and scripts
```

## 🧪 Testing

The project includes comprehensive tests:

```bash
# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e
```

## 📖 Documentation

- **[CLAUDE.md](CLAUDE.md)** - Project instructions and development context
- **[API Documentation](https://specify.firestitch.dev/api/wsdl)** - Specify API reference