# MCP Planning Server

MCP server for Claude Code that helps organize and track software development tasks.

## What is this?

This is a plugin for Claude Code (Anthropic's AI coding assistant). It adds planning tools that help:
- Break down complex tasks into steps
- Track what's done and what's next
- Record technical decisions
- Compare different solution approaches

## Prerequisites

Before installing, make sure you have:
- **Node.js** (version 18 or higher) - download from https://nodejs.org
- **Claude Code** - the CLI tool from Anthropic

To check if Node.js is installed, run in terminal:
```bash
node --version
```

## Installation

1. Clone or download this repository

2. Open terminal in the project folder

3. Install dependencies:
```bash
npm install
```

4. Build the project:
```bash
npm run build
```

After build, you should see a `dist` folder with compiled files.

## Configuration

To use this server with Claude Code, you need to add it to MCP settings.

### Step 1: Find your settings file

Settings can be placed in one of these locations:

| Location | File path | Use case |
|----------|-----------|----------|
| Project (private) | `.claude/settings.local.json` | Only for you, not shared |
| Project (shared) | `.claude/settings.json` | Shared with team via git |
| Global | `~/.claude/settings.json` | All your projects |

### Step 2: Add server configuration

Open or create the settings file and add:

```json
{
  "mcpServers": {
    "planning": {
      "command": "node",
      "args": ["FULL_PATH_TO/planner/dist/index.js"],
      "env": {
        "MCP_PLANNING_STORAGE_PATH": "./.mcp-plans"
      }
    }
  }
}
```

**Important:** Replace `FULL_PATH_TO` with the actual path to this folder.

Example paths:
- Windows: `D:/Projects/planner/dist/index.js`
- Mac/Linux: `/home/user/projects/planner/dist/index.js`

### Step 3 (Optional): Allow tools without confirmation

By default, Claude Code asks permission for each tool use. To skip confirmation for planning tools, add this section to your settings file:

```json
{
  "permissions": {
    "allow": [
      "mcp__planning"
    ]
  }
}
```

Your complete settings file will look like this:

```json
{
  "mcpServers": {
    "planning": {
      "command": "node",
      "args": ["FULL_PATH_TO/planner/dist/index.js"],
      "env": {
        "MCP_PLANNING_STORAGE_PATH": "./.mcp-plans"
      }
    }
  },
  "permissions": {
    "allow": [
      "mcp__planning"
    ]
  }
}
```

**Note:** Use exactly `mcp__planning` (not `mcp__planning__*`). Wildcards are not supported.

## How to use

Once configured, just talk to Claude Code naturally.

### Starting a new plan

Tell Claude Code what you want to build:

> "I need to build a user login system"

Claude Code will automatically:
1. Create a plan
2. Add requirements
3. Suggest solutions
4. Break work into phases

### Checking progress

Ask Claude Code about your plan:

> "What's the status of my plan?"
> "What should I work on next?"

### Updating progress

Tell Claude Code when you finish something:

> "I finished the login form"

Claude Code will update the plan and suggest what to do next.

## Available tools

The server provides tools in 8 categories:

| Category | Description |
|----------|-------------|
| Plan | Create and manage plans |
| Requirement | Define what needs to be built |
| Solution | Compare different approaches |
| Decision | Record technical choices |
| Phase | Break work into steps |
| Link | Connect related items |
| Query | Search and analyze plans |
| Artifact | Store code and configs |

## Where plans are stored

Plans are saved as JSON files:

```
.mcp-plans/
  plans/
    {plan-id}/
      manifest.json
      requirements.json
      solutions.json
      decisions.json
      phases.json
      links.json
      artifacts.json
  active-plans.json
```

## Troubleshooting

**Claude Code doesn't see the planning tools**
- Check that the path in settings is correct
- Make sure you ran `npm run build`
- Restart Claude Code after changing settings

**Permission errors**
- Check that the storage path is writable
- On Windows, avoid paths with spaces if possible

## License

MIT