README.md•4.28 kB
# 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)