Skip to content

Commit 19d9e0b

Browse files
ktamas77claude
andcommitted
chore(mcp): prepare for MCP Registry submission
Adds the metadata required to submit @squidcode/timebook to modelcontextprotocol/registry: - server.json at repo root, declaring name (io.github.squidcode/timebook), the npm package + entrypoint args ("mcp"), the GitHub source repo, and the upstream website. Schema-pinned to the 2025-09-29 server schema. - mcpName: "io.github.squidcode/timebook" in package.json. - <!-- mcp-name: io.github.squidcode/timebook --> at the top of README.md for ownership verification by the mcp-publisher CLI. README also gets the content reviewers look for: - A "Try it with prompts" section with five concrete end-to-end MCP prompts (start a timer, query past time, log past work with rate, query active timer, stop timer) — Claude Connectors review wants ≥3 examples in the docs. - A "Privacy" section documenting token storage location and permissions, the absence of telemetry, the role of the MCP host, and how to revoke the token. A missing privacy disclosure is an automatic Connectors rejection. - Minor doc updates: tools table now shows read-only / pagination hints, and the develop/release sections mention the new `npm test` step. Note on naming: the GitHub repo is squidcode/timebook-cli; the npm package and Registry namespace are @squidcode/timebook (no -cli). The server.json reflects this split. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 0fa6bfb commit 19d9e0b

2 files changed

Lines changed: 65 additions & 12 deletions

File tree

README.md

Lines changed: 37 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
<!-- mcp-name: io.github.squidcode/timebook -->
2+
13
# Timebook CLI
24

35
Command-line client and **MCP server** for [Timebook](https://usetimebook.com) — track time, manage timers, and expose your Timebook account to AI agents (Claude, Codex, Cursor, …) over the [Model Context Protocol](https://modelcontextprotocol.io).
@@ -88,16 +90,39 @@ The MCP server reuses the token saved by `timebook login` — run `timebook logi
8890

8991
### Tools exposed to the model
9092

91-
| Tool | What it does |
92-
| ------------------ | ------------------------------------------------ |
93-
| `whoami` | Current authenticated user |
94-
| `list_projects` | All projects in scope |
95-
| `list_clients` | All clients in scope |
96-
| `get_active_timer` | The running timer, or `null` |
97-
| `start_timer` | Start a timer on a project |
98-
| `stop_timer` | Stop the running timer |
99-
| `log_time` | Log a manual entry (`duration` OR `start`+`end`) |
100-
| `list_entries` | Recent entries, optional project + date filters |
93+
| Tool | What it does |
94+
| ------------------ | ------------------------------------------------------------ |
95+
| `whoami` | Current authenticated user (read-only) |
96+
| `list_projects` | All projects in scope (read-only) |
97+
| `list_clients` | All clients in scope (read-only) |
98+
| `get_active_timer` | The running timer, or `null` (read-only) |
99+
| `start_timer` | Start a timer on a project |
100+
| `stop_timer` | Stop the running timer |
101+
| `log_time` | Log a manual entry (`duration` OR `startTime`+`endTime`) |
102+
| `list_entries` | Recent entries (default 50, max 500), project + date filters |
103+
104+
### Try it with prompts
105+
106+
Once the MCP server is connected, ask the model in plain English:
107+
108+
- _"Start a timer on my Acme website project for landing-page wireframes."_
109+
- _"How much time did I log on the Recycler project last week?"_
110+
- _"Log 1 hour 30 minutes against ChatNexus from 9am this morning at the Software Development rate, with description 'code review of the auth refactor'."_
111+
- _"What am I currently working on?"_ — invokes `get_active_timer`.
112+
- _"Stop my timer."_
113+
114+
The model picks the right tool, asks `list_projects` first if it needs to disambiguate a name, and writes through `start_timer` / `log_time` / `stop_timer`.
115+
116+
## Privacy
117+
118+
Timebook CLI runs on your machine and only talks to your Timebook account.
119+
120+
- **Authentication**: `timebook login` mints a personal API token via Timebook's OAuth-style consent screen. The token is stored locally with `0600` permissions (`~/Library/Preferences/timebook/config.json` on macOS, `~/.config/timebook/config.json` on Linux, `%APPDATA%\timebook\Config\config.json` on Windows). It is never transmitted anywhere except `https://usetimebook.com` (or your override) on outgoing API calls.
121+
- **Telemetry**: none. Neither the CLI nor the MCP server reports usage, errors, or analytics anywhere.
122+
- **MCP host data**: when you use `timebook mcp` from inside Claude / Cursor / etc., the MCP host (not Timebook) controls what the model sees. Tool inputs and outputs flow through the host's normal model-context pipeline.
123+
- **Revoking access**: visit https://usetimebook.com/settings/api-tokens to revoke the token at any time.
124+
125+
For Timebook's product-level privacy policy, see https://usetimebook.com/privacy.
101126

102127
## Configuration
103128

@@ -125,14 +150,14 @@ cd timebook-cli
125150
npm install
126151
npm run dev -- --help # tsx-powered hot-loop
127152
npm run build # emits dist/
128-
npm run lint && npm run typecheck
153+
npm run lint && npm run typecheck && npm run test
129154
```
130155

131156
Pre-commit hooks (ESLint + Prettier via `lint-staged`) are wired up by `husky` on `npm install`.
132157

133158
## Release
134159

135-
`prepublishOnly` runs lint + typecheck + build, then:
160+
`prepublishOnly` runs lint + typecheck + tests + build, then:
136161

137162
```bash
138163
npm publish --access public

server.json

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
3+
"name": "io.github.squidcode/timebook",
4+
"description": "Track time, manage timers, and read your Timebook (usetimebook.com) account from any MCP client. Exposes start_timer, stop_timer, log_time, list_projects, list_clients, list_entries, get_active_timer, and whoami.",
5+
"version": "0.1.4",
6+
"repository": {
7+
"url": "https://github.com/squidcode/timebook-cli",
8+
"source": "github"
9+
},
10+
"websiteUrl": "https://usetimebook.com",
11+
"packages": [
12+
{
13+
"registryType": "npm",
14+
"registryBaseUrl": "https://registry.npmjs.org",
15+
"identifier": "@squidcode/timebook",
16+
"version": "0.1.4",
17+
"transport": {
18+
"type": "stdio"
19+
},
20+
"runtimeArguments": [
21+
{
22+
"type": "positional",
23+
"value": "mcp"
24+
}
25+
]
26+
}
27+
]
28+
}

0 commit comments

Comments
 (0)