npm package: @segosolutions/mcp-server
Description: MCP server for Sego PM - enables Claude to manage tasks via API
Author: Sego Solutions
Latest version: 1.0.1

# Sego PM MCP Server

Model Context Protocol (MCP) server for [Sego PM](https://sego.pm) task management. This server allows Claude (or any MCP-compatible AI) to interact with your Sego PM tasks - query tasks, update statuses, add comments, create projects from codebases, and more.

## Installation

```bash
npm install -g @segosolutions/mcp-server
```

Or use npx directly:

```bash
npx @segosolutions/mcp-server
```

## Prerequisites

1. **Sego PM Account** - Sign up at https://sego.pm
2. **API Key** - Generate from Developer Dashboard → API Keys
3. **Node.js 18+**

## Quick Start

### 1. Get Your API Key

1. Log into Sego PM at https://sego.pm
2. Navigate to Developer Dashboard → API Keys
3. Click "Create New API Key"
4. Copy the key (format: `sk_dev_XXXX...`)

### 2. Configure Claude Desktop

Add to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "sego-pm": {
      "command": "npx",
      "args": ["-y", "@segosolutions/mcp-server"],
      "env": {
        "SEGO_API_KEY": "sk_dev_your_api_key_here",
        "SEGO_API_URL": "https://sego.pm"
      }
    }
  }
}
```

### 3. Restart Claude Desktop

The MCP server will connect automatically on startup.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SEGO_API_KEY` | Yes | - | Your Sego PM API key |
| `SEGO_API_URL` | No | `http://localhost:3000` | Sego PM API URL |

You can also use a `.env` file in your project directory.

## Available Tools

### Task Management

#### `get_my_tasks`
Get tasks assigned to you, optionally filtered by project or status.

```
Show me all my tasks in progress
```

#### `search_tasks`
Search tasks by keyword in title, description, or technical notes.

```
Search for tasks related to authentication
```

#### `update_task_status`
Update the status of a task (with workflow validation).

```
Move task abc123 to in progress
```

#### `add_task_comment`
Add a comment to a task (supports markdown).

```
Add a comment to task abc123 saying "Implemented basic auth flow"
```

#### `assign_task`
Assign a task to yourself or another user.

```
Assign task abc123 to me
```

### Client Requests

#### `get_client_request`
Get a client request with all associated tasks and context.

#### `search_client_requests`
Search client requests by project, status, or keyword.

### Projects

#### `create_project_from_codebase`
Create a Sego PM project from a local codebase with CLAUDE.md file. Auto-extracts project name, description, and tech stack.

```
Create a Sego PM project from this codebase
```

## Available Resources

### Task Detail
URI: `sego://tasks/{taskId}`

Get detailed information about a specific task including comments and full context.

### Client Request Detail
URI: `sego://client-requests/{requestId}`

Get detailed information about a client request including all associated tasks.

## Usage Examples

### Daily Standup
```
Claude, give me a summary of my tasks:
- What's in progress?
- What's blocked?
- What's in review?
```

### Working on a Task
```
I'm working on the password reset task.
Move it to in progress and show me the full details.
```

### Completing Work
```
I've finished the user export feature in task xyz789.
Add a comment with what I did and move it to in review.
```

### Creating a Project
```
Create a Sego PM project from this codebase.
My CLAUDE.md file is in the project root.
```

## Task Status Workflow

Valid transitions:
- `AI_REVIEW` → `DRAFT`, `BACKLOG`, `CANCELLED`
- `DRAFT` → `BACKLOG`, `CANCELLED`
- `BACKLOG` → `IN_PROGRESS`, `CANCELLED`
- `IN_PROGRESS` → `IN_REVIEW`, `BLOCKED`, `BACKLOG`
- `BLOCKED` → `IN_PROGRESS`, `BACKLOG`
- `IN_REVIEW` → `COMPLETED`, `IN_PROGRESS`
- `COMPLETED` → (terminal)
- `CANCELLED` → (terminal)

## Development

### Local Development

```bash
# Clone the repo
git clone https://github.com/sego-solutions/sego-pm
cd sego-pm/mcp-server

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your API key

# Run in development mode
npm run dev

# Build
npm run build

# Run built version
npm start
```

### Testing

```bash
# Type checking
npm run typecheck
```

## Troubleshooting

### MCP Server Not Connecting

1. Check API key is valid and not expired
2. Verify SEGO_API_URL is correct
3. Check Claude Desktop logs:
   - macOS: `~/Library/Logs/Claude/`
   - Windows: `%APPDATA%\Claude\logs\`

### Invalid Status Transition

Tasks must follow the workflow (e.g., can't jump from BACKLOG to COMPLETED directly).

### Permission Denied

Only tasks you're assigned to or created are accessible.

## Support

- Documentation: https://sego.pm/docs
- Issues: https://github.com/sego-solutions/sego-pm/issues

## License

MIT - See [LICENSE](LICENSE)