Specify MCP Server

A Model Context Protocol (MCP) 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)

npm install -g @firestitch/specifymcp

Option 2: Install from source

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):

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

For source installation

{
  "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:

   auth --email="[email protected]" --password="your-password" --environment="dev"

2. Set current project context:

   list_projects --limit=10
   set_current_project --projectId=123

3. Use tools without specifying project:

   list_tasks --assignedToMe=true
   create_task --name="New feature" --priority=30

Workflow Examples

ERD Creation:

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:

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:

# Run all tests
npm test

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

📖 Documentation

• CLAUDE.md - Project instructions and development context
• API Documentation - Specify API reference