# taskmaster-mcp

A TypeScript [MCP](https://modelcontextprotocol.io) server that gives Claude, Cursor
and other MCP hosts a set of Jira tools. Built on
[FastMCP](https://github.com/punkpeye/fastmcp) + Express. This is a trimmed-down version of something we actually run internally.

Treat this as your first week on the team: get it running, poke around, find
something worth improving, and ship it as a pull request.

We haven't told you what to build. Deciding that is part of the exercise.

---

## 1. Make your own copy

**Use the template — don't fork.**

1. On the repo page, click **Use this template** → **Create a new repository**.
2. Name it whatever you like.
3. **Set the visibility to Private.**
4. Create the repository.

Then add **@laurence-barry**, **@dave-r-cintra** and **connorb-cintra** as collaborators: your repo →
Settings → Collaborators → Add people.

## 2. Get a Jira instance

You'll need your own Jira Cloud site — the free tier takes about five minutes and
doesn't need a card.

1. Sign up at [atlassian.com/software/jira/free](https://www.atlassian.com/software/jira/free).
2. Create a project. A **Scrum** template gives you a backlog and sprint board,
  which `next_jira_task` expects. Note the project key (e.g. `PROJ`).
3. Generate an API token at
  [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).

Spend a couple of minutes creating issues with a mix of types, statuses and
priorities, plus a subtask and an epic link. Several tools walk those relationships
and an empty board won't show you much.

## 3. Run it

Requires Node 22+.

```bash
npm install
cp example.env .env        # fill in your Jira values
npm run dev                # http://localhost:3000
```

```
JIRA_API_URL=https://your-domain.atlassian.net
JIRA_EMAIL=the-email-you-signed-up-with@example.com
JIRA_API_TOKEN=<token from step 3 above>
JIRA_PROJECT=<your project key, e.g. PROJ>
ALLOW_UNAUTHENTICATED_LOCAL=true
```

Four tools call Claude for ticket content — add `ANTHROPIC_API_KEY` from
[console.anthropic.com](https://console.anthropic.com) if you want those. The
others work without it.

### Connect an MCP client

Point the client at `http://localhost:3000/mcp`.

**Claude Code:**

```bash
claude mcp add --transport http taskmaster http://localhost:3000/mcp
```

**Cursor** — in `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "taskmaster": {
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

With `ALLOW_UNAUTHENTICATED_LOCAL=true`, localhost requests use your `.env`
credentials. Try the tools out properly before you write any code — most of what's
interesting here only shows up once you've used the thing.

```bash
curl -s http://localhost:3000/health
```

---



## 4. Build something

Pick a feature or improvement you think the project should have, and implement it.

Good choices tend to be things you noticed *while using it* — a rough edge, a gap in
the tool coverage, something that broke when you fed it real data. We're more
interested in a small, well-judged, complete change than a large half-finished one.

Work in a branch and open a pull request against `main` in your own repo. Don't
merge it — leave it open for us to review.

### Your PR description should cover

- **What you built**, briefly.
- **Why you chose it** over the other things you noticed.
- **Trade-offs** you made, and anything you'd do differently with more time.

This matters as much as the code. A short, clear write-up beats a long one.



---

## What we're looking for


|                   |                                                                                  |
| ----------------- | -------------------------------------------------------------------------------- |
| **Judgement**     | Did you pick something that genuinely improves the project, and can you say why? |
| **Craft**         | Does the change fit the codebase's existing patterns and conventions?            |
| **Communication** | Does the PR explain itself to someone who wasn't there?                          |
| **Tool use**      | How well do you work with AI — steering it, checking it, rejecting it?           |


We won't be scoring you on the size of the diff.

---