@timesheetai/mcp 0.1.0-alpha.3 → 0.1.0-alpha.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +28 -19
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -12,6 +12,10 @@ on your behalf, without leaving your editor.
12
12
  Motivating workflow: at the end of the day, ask your agent to summarize what it
13
13
  worked on and have it call `add_time_entry` to record the time directly.
14
14
 
15
+ ![TimesheetAI MCP — Claude Desktop demo](https://assets.timesheetai.app/images/mcp-demo.png)
16
+
17
+ > **Step-by-step setup guide with screenshots:** [alpha.timesheetai.app/help/mcp](https://alpha.timesheetai.app/help/mcp)
18
+
15
19
  ## Tools
16
20
 
17
21
  | Tool | What it does |
@@ -109,30 +113,35 @@ env = { TIMESHEETAI_API_KEY = "ak_...", TIMESHEETAI_BASE_URL = "https://alpha.ti
109
113
 
110
114
  ## Local development
111
115
 
112
- Build, then run the compiled entrypoint directly:
116
+ Inspect the server interactively with the MCP Inspector:
113
117
 
114
118
  ```bash
115
- pnpm --filter @timesheetai/mcp build
116
- TIMESHEETAI_API_KEY=ak_... TIMESHEETAI_BASE_URL=http://localhost:5173 \
117
- node packages/mcp/dist/index.js
119
+ TIMESHEETAI_API_KEY=ak_... \
120
+ npx @modelcontextprotocol/inspector npx -y @timesheetai/mcp@alpha
118
121
  ```
119
122
 
120
- Before the package is published to npm, wire it into Claude Code by pointing at
121
- the **built `dist/` path** instead of `npx @timesheetai/mcp` (rebuild after any
122
- source change). Create the API key from the dev Account Portal → API keys; a
123
- key from your dev Clerk instance authenticates against the dev backend
124
- (`http://localhost:5173`):
123
+ ## How it works
125
124
 
126
- ```bash
127
- claude mcp add timesheetai \
128
- --env TIMESHEETAI_API_KEY=ak_... \
129
- --env TIMESHEETAI_BASE_URL=http://localhost:5173 \
130
- -- node /absolute/path/to/timesheet-app/packages/mcp/dist/index.js
125
+ This package is a thin **stdio MCP server** that proxies tool calls to the
126
+ TimesheetAI backend over authenticated HTTP. No database credentials or secrets
127
+ are ever exposed to the agent.
128
+
129
+ ```
130
+ Agent (Claude, Codex, …)
131
+ ↓ MCP tool call (stdio)
132
+ @timesheetai/mcp (this package)
133
+ ↓ HTTP + Bearer token
134
+ TimesheetAI backend
135
+ ↓ API key verification → user + workspace resolution
136
+ ↓ Database
131
137
  ```
132
138
 
133
- Inspect interactively with the MCP Inspector:
139
+ **Typical agent flow:**
134
140
 
135
- ```bash
136
- TIMESHEETAI_API_KEY=ak_... TIMESHEETAI_BASE_URL=http://localhost:5173 \
137
- npx @modelcontextprotocol/inspector node packages/mcp/dist/index.js
138
- ```
141
+ 1. `list_projects` (optionally with `search`) → get `projectId` and `taskId`
142
+ 2. `add_time_entry` → log the entry (idempotent on `clientRefId`)
143
+ 3. `list_entries` → verify what was logged
144
+ 4. `delete_time_entry` → correct a mistake
145
+
146
+ **Time format:** all times are wall-clock (`HH:mm`), dates `YYYY-MM-DD`.
147
+ The agent resolves "today" to an explicit date — the server never infers timezones.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@timesheetai/mcp",
3
- "version": "0.1.0-alpha.3",
3
+ "version": "0.1.0-alpha.4",
4
4
  "description": "MCP server for TimesheetAI (alpha) — connect AI agents (Claude, Codex, Cursor) to your timesheet. Sign up at alpha.timesheetai.app.",
5
5
  "license": "MIT",
6
6
  "comment:dist-tag": "Published under the `alpha` npm dist-tag while DEFAULT_BASE_URL points at alpha. Install with `@timesheetai/mcp@alpha`. At production launch: flip DEFAULT_BASE_URL to production, bump to a stable version, and publish to `latest`.",