# Basecamp MCP Server (TypeScript)

A Model Context Protocol (MCP) server that exposes Basecamp tools to AI assistants (e.g., VS Code Chat in Agent mode).  
Supports projects, to‑do sets/lists, messages (with rendered content), and creating to‑dos.

---

## Features

- **Projects**

  - `list_projects` — rich listing (status, timestamps, purpose, client flags, bookmarks, enabled _dock_ tools)
  - Pagination via HTTP `Link` header (exposes `nextPage`)
  - Optional raw dock objects

- **To‑do sets / lists**

  - Resolves a project’s **to‑do set** from the project **dock**
  - `get_todoset` — returns to‑do set id/url; optional lists
  - `list_todolists` — lists to‑do lists for a project’s to‑do set

- **Messages**

  - `list_messages` — resolves the project Message Board from dock, lists messages with pagination
  - Optional **full content rendering** (`markdown`/`html`/`text`)
  - `get_message` — fetch a single message (rendered or raw JSON)

- **To‑dos**
  - `create_todo` — create a to‑do in a list (title, description, optional `due_on`)

---

## Project layout

```
src/
├─ lib/
│  └─ basecamp.ts          # Basecamp client (auth refresh, requests, pagination)
├─ tools/
│  ├─ projects.ts          # list_projects
│  ├─ todosets.ts          # get_todoset, list_todolists
│  ├─ messages.ts          # list_messages, get_message
│  └─ todos.ts             # create_todo
└─ basecamp-mcp.ts         # entrypoint (register tools, start stdio server)
```

---

## Quick start

```bash
# 1) Install dependencies
npm install

# 2) Build
npm run build

# 3) (Optional) sanity check
node build/basecamp-mcp.js
# (MCP servers sit and wait on stdio; no output is expected here)
```

### Environment variables

Add your required values **in a `.env` file** at the project root.  
This file is referenced by the MCP server configuration below.

> Do **not** commit your `.env` file to version control.

---

## Configure in VS Code (MCP)

Create `.vscode/mcp.json` in this project:

```json
{
  "servers": {
    "basecamp": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/build/basecamp-mcp.js"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}
```

Now restart the server from VS Code:

- **Command Palette → “MCP: List Servers” → basecamp → Start/Restart**
- Open **Chat**, switch to **Agent**, enable the **basecamp** tools.

---

## Example tool calls (Agent mode)

**Projects (JSON with dock):**

```
Run basecamp.list_projects with { "format": "json", "dock_detail": true, "limit": 5 }
```

or natural language

```
retrieve all project information
```

**Resolve to‑do set and lists:**

```
Run basecamp.get_todoset with { "project_id": 123456789 }
Run basecamp.list_todolists with { "project_id": 123456789 }
```

Natural language example

```
show todo sets and lists for project "{{prpjectName / Id}}"
```

**Create a to‑do:**

```
Run basecamp.create_todo with { "project_id": 123456789, "todolist_id": 222222222, "content": "Kickoff", "due_on": "2025-09-30" }
```

Natural language example

```
create a to-do in the "{to do list name}", titled "Update README.md"
```

**Messages (rendered content):**

```
Run basecamp.list_messages with { "project_id": 123456789, "page": 1, "format": "markdown", "include_body": true }
Run basecamp.get_message with { "project_id": 123456789, "message_id": 987654321, "render": "markdown" }
```

or

```
get all messages from TestMCP project
```

```
get content for this message "{messageId / title"
```

> **Pagination**: responses include `nextPage` from the RFC5988 `Link` header. Call again with `{ "page": <nextPage> }`.

---

## Troubleshooting (quick)

- **ESM import errors**: make sure your project is configured for ESM/NodeNext (standard TS/Node setup).
- **401/429 from API**: verify tokens and reduce request volume; the client retries once on `429` using `Retry-After`.
- **No to‑do set / message board**: that project may not have those tools enabled in its dock.

---

## License

[ISC](LICENCE.md)

## Acknowledgments

- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
- [Basecamp API](https://github.com/basecamp/bc3-api/tree/master)