@timetick/mcp 0.2.1 → 0.3.0

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 (5) hide show
  1. package/LICENSE +662 -0
  2. package/README.md +65 -70
  3. package/dist/index.js +3100 -284
  4. package/package.json +8 -4
  5. package/dist/index.js.map +0 -1
package/README.md CHANGED
@@ -1,113 +1,108 @@
1
1
  # @timetick/mcp
2
2
 
3
- Model Context Protocol (MCP) server for [Timetick](https://timetick.io) — drive EV charger simulators, OCPP tests and real hardware from an AI client, in plain language.
3
+ Model Context Protocol (MCP) server for [Timetick](https://timetick.io). It lets an AI client simulate EV chargers, test a CSMS or a real charger over OCPP 1.6 and 2.0.1, and analyze the results. In plain language: _"I want to test my CSMS"_, and the agent signs you in, sets everything up, runs the test and tells you what happened.
4
4
 
5
- Built on the official [`@timetick/sdk`](https://www.npmjs.com/package/@timetick/sdk).
5
+ Day-to-day work runs through the MCP tools. The web portal is still needed for billing, API keys on Google or LinkedIn accounts, resetting a password, and security profiles (Basic Auth or certificates towards a CSMS).
6
6
 
7
- ## Quick start
7
+ ## Install
8
8
 
9
- Generate an API key in the Timetick portal under **Account (top-right corner) → API keys**, then register the server with your MCP client. For Claude Desktop, in `claude_desktop_config.json`:
9
+ ### Claude Code
10
+
11
+ ```
12
+ claude mcp add timetick -- npx -y @timetick/mcp@latest
13
+ ```
14
+
15
+ ### Codex
16
+
17
+ ```
18
+ codex mcp add timetick -- npx -y @timetick/mcp@latest
19
+ ```
20
+
21
+ ### Gemini CLI, Claude Desktop, Cursor and other MCP clients
10
22
 
11
23
  ```json
12
24
  {
13
25
  "mcpServers": {
14
26
  "timetick": {
15
27
  "command": "npx",
16
- "args": ["-y", "@timetick/mcp"],
17
- "env": { "TIMETICK_API_TOKEN": "your_api_key_here" }
28
+ "args": ["-y", "@timetick/mcp@latest"]
18
29
  }
19
30
  }
20
31
  }
21
32
  ```
22
33
 
23
- Restart the client and ask for something:
34
+ Keep `@latest`: `npx` otherwise keeps running a cached old version after the API has moved on.
24
35
 
25
- - _"list my simulators"_
26
- - _"power on CP-001"_
27
- - _"create a full charge cycle test and run it on CP-001"_
36
+ ## Sign in
28
37
 
29
- Cursor, Claude Code and other MCP clients take the same command and environment variable.
38
+ Ask the agent anything, or call `login`. It opens a one-time page in your local browser where you sign in, create an account or paste an API key. What you type goes to the MCP server on your machine and from there to Timetick; it never enters the AI conversation. The server creates a key named after your machine and stores it at `~/.timetick/credentials.json` with permissions `0600`.
30
39
 
31
- ## Configuration
40
+ - **Google or LinkedIn accounts:** create a key in the portal under **API keys** and paste it on the same page.
41
+ - **No local browser** (SSH, containers): set `TIMETICK_API_TOKEN`. It always wins over stored credentials.
42
+ - `whoami` shows who you are, the server version and whether an update is available. `logout` revokes the key and deletes it locally.
32
43
 
33
- | Env var | Required | Description |
34
- | -------------------- | -------- | ------------------------------------------------------------ |
35
- | `TIMETICK_API_TOKEN` | yes | Your Timetick API key, sent as `x-api-key` |
36
- | `TIMETICK_API_URL` | no | API endpoint (defaults to `https://app.timetick.io/graphql`) |
37
- | `TIMETICK_MCP_READONLY` | no | `1` or `true` — read-only mode, see below |
44
+ ## Testing your CSMS
38
45
 
39
- ## Read-only mode
46
+ Simulators connect to your CSMS from Timetick's cloud, so it needs a public `ws://` or `wss://` address. The simulator name is the charge point identity your CSMS sees.
40
47
 
41
- With `TIMETICK_MCP_READONLY=1` the server registers only tools annotated `readOnlyHint: true`; `power_on_simulator`, `power_off_simulator`, `run_simulator_action`, `create_test`, `run_test` and `stop_test_run` are left out.
48
+ | Under test | Connection | Charger-side steps | `Remote:` steps |
49
+ | --- | --- | --- | --- |
50
+ | Your CSMS | Simulators connect to it | Automatic | You send the command from your CSMS |
51
+ | Your real charger | Hardware connects to Timetick's CSMS | A person at the charger | Automatic |
42
52
 
43
- ## Projects and sim worlds
53
+ A `Remote:` step on a simulator waits for your CSMS to send the command. With expected results it passes or fails on its own; otherwise the agent asks you what happened and calls `complete_test_step` or `fail_test_step`.
44
54
 
45
- Most tools work inside a project's sim world and resolve it for you.
55
+ ## Tools
46
56
 
47
- | Situation | What happens |
48
- | ------------------------ | ---------------------------------------------------------------- |
49
- | Your key has one project | It is selected automatically |
50
- | Your key has several | Call `use_project` once, by name or id; it holds for the session |
51
- | Any time | `get_context` reports the active project and sim world |
57
+ Projects, simulators and hardware are addressed by name or id. `simulator` also accepts a portal link. Tests, plans and runs are addressed by id; the `list_*` tools return them.
52
58
 
53
- Pass `project` to a tool to target a different project for that call alone. The session's active project stays where it is.
59
+ **Account**: `login`, `logout`, `whoami`, `update_profile`, `list_api_keys`, `create_api_key`, `rotate_api_key`, `delete_api_key`
54
60
 
55
- ## Tools
61
+ **Projects**: `get_context`, `use_project`, `list_projects`, `create_project`, `start_trial`, `update_project`, `delete_project`
56
62
 
57
- Projects, simulators and tests are addressed by name or by id, whichever you have.
63
+ **Setup**: `list_endpoints`, `create_endpoint`, `update_endpoint`, `delete_endpoint`, `list_simulator_configs`, `get_simulator_config`, `create_simulator_config`, `update_simulator_config`, `delete_simulator_config`, `list_manufacturers`, `create_manufacturer`, `update_manufacturer`, `delete_manufacturer`, `list_models`, `create_model`, `update_model`, `delete_model`, `list_ocpp_configs`, `get_ocpp_config`, `create_ocpp_config`, `update_ocpp_config`, `delete_ocpp_config`, `list_tags`, `create_tag`, `update_tag`, `delete_tag`, `link_tag`, `unlink_tag`
58
64
 
59
- ### Context
65
+ **Simulators**: `list_simulators`, `get_simulator`, `create_simulator`, `create_simulators_bulk`, `update_simulator`, `delete_simulator`, `power_on_simulator`, `power_off_simulator`, `update_simulator_ocpp_key`, `run_step`
60
66
 
61
- | Tool | Description |
62
- | ------------- | -------------------------------- |
63
- | `get_context` | The active project and sim world |
64
- | `use_project` | Switch the active project |
67
+ **Hardware**: `list_hardware`, `get_hardware`, `create_hardware`, `update_hardware`, `delete_hardware`
65
68
 
66
- ### Inspect
69
+ **Tests**: `list_actions`, `get_action`, `list_expected_result_commands`, `list_test_templates`, `create_test_from_template`, `list_tests`, `get_test`, `create_test`, `update_test`, `delete_test`
67
70
 
68
- | Tool | Description |
69
- | ----------------- | ------------------------------------------------------- |
70
- | `list_projects` | Projects your API key can reach |
71
- | `list_simulators` | Virtual chargers, filtered by name or protocol |
72
- | `get_simulator` | One simulator: network status, power status, connectors |
73
- | `list_hardware` | Physical OCPP devices |
74
- | `list_actions` | The step library available for building tests |
71
+ **Runs**: `run_test`, `get_test_run`, `get_test_run_details`, `list_test_runs`, `list_latest_test_runs`, `complete_test_step`, `fail_test_step`, `stop_test_run`, `update_test_run`, `delete_test_run`, `get_simulator_logs`
75
72
 
76
- Lists come back 20 rows per page. Pass `page` and `pageSize` for the rest; every reply reports the total.
73
+ **Stress tests**: `run_stress_test`, `list_stress_tests`, `get_stress_test`, `stop_stress_test`
77
74
 
78
- ### Support (read-only)
75
+ **Test plans**: `list_test_plans`, `get_test_plan`, `create_test_plan`, `update_test_plan`, `launch_test_plan`, `stop_test_plan`, `delete_test_plan`
79
76
 
80
- | Tool | Description |
81
- | ---------------------- | ----------------------------------------------------------------------------------- |
82
- | `get_simulator_config` | OCPP keys (credential values masked), behavior, model, connector types, last run |
83
- | `get_simulator_logs` | OCPP messages in a window: `from`/`to` (ISO) or `last` (`30m`, `6h`), `limit`, `action` |
84
- | `get_test_run_details` | A run's status and fail reason, one page of its simulators (`page`), and the steps of one `simulator` |
77
+ Lists return 20 rows per page. Pass `page` and `pageSize` for the rest; every reply reports the total.
85
78
 
86
- The `simulator` argument of every tool also takes a portal link, e.g. `https://app.timetick.io/projects/1/simulators/42?tab=testPlays`. A link is resolved by the simulator id in it, never by name.
79
+ ## Several accounts
87
80
 
88
- ### Control simulators
81
+ `whoami` shows the account in use. To switch, call `login` again, which replaces the stored key and revokes the old one if `login` created it. To use two accounts side by side, add the server twice with a different `TIMETICK_CREDENTIALS_PATH` or `TIMETICK_API_TOKEN` on each.
89
82
 
90
- | Tool | Description |
91
- | ---------------------- | -------------------------------------------------------------------- |
92
- | `power_on_simulator` | Boot a simulator and connect it to the OCPP server |
93
- | `power_off_simulator` | Shut a simulator down |
94
- | `run_simulator_action` | Run one step — reset, plug in, plug out — with `key=value` arguments |
83
+ ## Projects
95
84
 
96
- ### Tests
85
+ | Situation | What happens |
86
+ | --- | --- |
87
+ | Your account has one project | It is selected automatically |
88
+ | Your account has several | Call `use_project` once, by name or id; it holds for the session |
89
+ | You create your first project | It becomes the active one, and its free trial starts |
90
+ | You already have a project | Another one needs payment details, set up in the portal |
91
+ | A project's trial has not started | It is read-only until its owner calls `start_trial`, usually after an unfinished portal onboarding |
92
+ | A project's plan has ended | It is read-only until a plan is set up in the portal |
93
+ | Any time | `get_context` reports the active project |
97
94
 
98
- | Tool | Description |
99
- | ------------- | ----------------------------------------------- |
100
- | `list_tests` | Tests in the active sim world |
101
- | `get_test` | One test, with its device requirements |
102
- | `create_test` | Build a test from an ordered list of step names |
95
+ Pass `project` to a tool to target a different project for that call alone.
103
96
 
104
- ### Run and monitor
97
+ ## Configuration
98
+
99
+ | Env var | Description |
100
+ | --- | --- |
101
+ | `TIMETICK_API_TOKEN` | API key; skips login and wins over stored credentials |
102
+ | `TIMETICK_API_URL` | API endpoint, default `https://app.timetick.io/graphql`. Stored credentials only apply to the endpoint they were created for |
103
+ | `TIMETICK_MCP_READONLY` | `1` or `true`: read-only mode, see below |
104
+ | `TIMETICK_CREDENTIALS_PATH` | Where login stores the key, default `~/.timetick/credentials.json` |
105
105
 
106
- | Tool | Description |
107
- | ---------------- | --------------------------- |
108
- | `run_test` | Start a test on a simulator |
109
- | `get_test_run` | Status of a run |
110
- | `list_test_runs` | Recent runs |
111
- | `stop_test_run` | Shut a run down |
106
+ ## Read-only mode
112
107
 
113
- A simulator runs one test at a time. If it is busy, `run_test` says so and starts nothing — stop the run that holds it with `stop_test_run`, then ask again.
108
+ With `TIMETICK_MCP_READONLY=1` the server registers only tools annotated `readOnlyHint: true`. Login, logout and `whoami` stay available, since a read-only session could not start without them.