# collabnotes

collabnotes works with collaborative notes in HackMD: it reads the
authenticated user's profile, teams, and reading history, lists team
and personal notes, and creates, updates, and deletes notes in both
places. It talks to the public HackMD API v1 on your behalf, using a
personal API token you supply.

This package is a clean-room rebuild covering the full documented
tool set (12 tools) of the original HackMD MCP server.

## How it talks to the service

Every tool needs a HackMD API token:

```bash
export HACKMD_API_TOKEN="your token"
# Optional override (default: https://api.hackmd.io/v1)
export HACKMD_API_URL="https://api.hackmd.io/v1"
```

With no token set, every call fails with an error naming
`HACKMD_API_TOKEN`, before any request is made.

Requests carry `Authorization: Bearer HACKMD_API_TOKEN`. Path
segments such as team paths and note IDs are URL-encoded. Responses
are returned as parsed JSON; delete calls and empty-body responses
resolve to `{"status": "ok", ...}` carrying the IDs involved, and an
upstream HTTP error is reported with its status and body. Note that
the HackMD API's create/update permission fields are not part of this
tool spec: creates send only `title` and `content`, and updates send
only `content`.

## Install

```bash
npx @reneturcios/collabnotes list_user_notes '{}'
```

Or run the container image:

```bash
docker run -i ghcr.io/cloudcorprecords/collabnotes
```

The container defaults to the MCP server. Pass CLI arguments to use
it as a CLI instead.

## CLI

The CLI mirrors the tools: one subcommand per tool, taking its
arguments as a single JSON object.

```bash
collabnotes get_user_info '{}'
collabnotes list_teams '{}'
collabnotes get_history '{}'
collabnotes list_team_notes '{"teamPath":"my-team"}'
collabnotes create_team_note '{"teamPath":"my-team","title":"Spec","content":"# Spec"}'
collabnotes update_team_note '{"teamPath":"my-team","noteId":"abc","content":"# v2"}'
collabnotes delete_team_note '{"teamPath":"my-team","noteId":"abc"}'
collabnotes list_user_notes '{}'
collabnotes get_note '{"noteId":"abc"}'
collabnotes create_note '{"title":"Note","content":"# Note"}'
collabnotes update_note '{"noteId":"abc","content":"# v2"}'
collabnotes delete_note '{"noteId":"abc"}'
collabnotes --version
```

Exit codes: `0` on success, `1` on an API or validation error (the
error names the problem), `2` for usage errors.

## MCP server

One bin serves both faces. The `mcp` subcommand starts a stdio MCP
server:

```bash
npx -y @reneturcios/collabnotes mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "collabnotes": {
      "command": "npx",
      "args": ["-y", "@reneturcios/collabnotes", "mcp"],
      "env": { "HACKMD_API_TOKEN": "your token" }
    }
  }
}
```

### Tools

| Tool | Input | What it does |
| --- | --- | --- |
| `get_user_info` | (none) | Get the authenticated HackMD user's information. (`GET /me`) |
| `list_teams` | (none) | List the teams the authenticated user belongs to. (`GET /teams`) |
| `get_history` | (none) | Get the authenticated user's note reading history. (`GET /history`) |
| `list_team_notes` | `teamPath` (required) | List the notes belonging to a team. |
| `create_team_note` | `teamPath`, `title`, `content` (all required) | Create a new note in a team. |
| `update_team_note` | `teamPath`, `noteId`, `content` (all required) | Update the content of a team note. |
| `delete_team_note` | `teamPath`, `noteId` (required) | Delete a team note. |
| `list_user_notes` | (none) | List the authenticated user's own notes. (`GET /notes`) |
| `get_note` | `noteId` (required) | Get a single note by its ID. |
| `create_note` | `title`, `content` (required) | Create a new personal note. |
| `update_note` | `noteId`, `content` (required) | Update the content of a personal note. |
| `delete_note` | `noteId` (required) | Delete a personal note. |

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx
```

## License

MIT — see `LICENSE`.