@timetick/mcp 0.3.0 → 0.3.1

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 +29 -59
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,24 +1,22 @@
1
1
  # @timetick/mcp
2
2
 
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
-
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).
3
+ Run [Timetick](https://timetick.io) from your AI client. Say "I want to test my CSMS" and the agent signs you in, sets up simulators, runs the test and explains the result. It works with OCPP 1.6 and 2.0.1, and can test a CSMS or a real charger.
6
4
 
7
5
  ## Install
8
6
 
9
- ### Claude Code
7
+ Claude Code:
10
8
 
11
9
  ```
12
10
  claude mcp add timetick -- npx -y @timetick/mcp@latest
13
11
  ```
14
12
 
15
- ### Codex
13
+ Codex:
16
14
 
17
15
  ```
18
16
  codex mcp add timetick -- npx -y @timetick/mcp@latest
19
17
  ```
20
18
 
21
- ### Gemini CLI, Claude Desktop, Cursor and other MCP clients
19
+ Gemini CLI, Claude Desktop, Cursor and other MCP clients:
22
20
 
23
21
  ```json
24
22
  {
@@ -31,78 +29,50 @@ codex mcp add timetick -- npx -y @timetick/mcp@latest
31
29
  }
32
30
  ```
33
31
 
34
- Keep `@latest`: `npx` otherwise keeps running a cached old version after the API has moved on.
32
+ Keep `@latest` so you stay on the current version.
35
33
 
36
34
  ## Sign in
37
35
 
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`.
39
-
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.
43
-
44
- ## Testing your CSMS
45
-
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.
47
-
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 |
36
+ Ask the agent to log in to Timetick. A page opens in your browser where you can sign in, create an account or paste an API key. Your password stays out of the AI conversation.
52
37
 
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`.
38
+ If you use Google or LinkedIn to sign in, create an API key in the portal under **API keys** and paste it on that page.
54
39
 
55
- ## Tools
40
+ On a machine with no browser, such as over SSH, set `TIMETICK_API_TOKEN` to your API key in the client config.
56
41
 
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.
42
+ To switch accounts, ask the agent to log in again. To use two accounts at once, add the server twice, each with its own `TIMETICK_API_TOKEN`.
58
43
 
59
- **Account**: `login`, `logout`, `whoami`, `update_profile`, `list_api_keys`, `create_api_key`, `rotate_api_key`, `delete_api_key`
44
+ ## Test your CSMS
60
45
 
61
- **Projects**: `get_context`, `use_project`, `list_projects`, `create_project`, `start_trial`, `update_project`, `delete_project`
46
+ Simulators connect to your CSMS from Timetick's cloud, so it needs a public `ws://` or `wss://` address. Your CSMS sees the simulator's name as the charge point identity.
62
47
 
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`
48
+ Steps on the charger side, such as plugging in, run automatically. Steps named `Remote:` wait for your CSMS to send the command. If you set expected results, the step passes or fails on its own. Otherwise the agent asks you what happened.
64
49
 
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`
50
+ ## Test a real charger
66
51
 
67
- **Hardware**: `list_hardware`, `get_hardware`, `create_hardware`, `update_hardware`, `delete_hardware`
52
+ Your charger connects to Timetick's CSMS. Someone at the charger does the physical steps, and `Remote:` steps run automatically.
68
53
 
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`
54
+ ## What you can do
70
55
 
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`
56
+ - Create and manage simulators, hardware, models and OCPP configurations
57
+ - Write tests or start from a template
58
+ - Run tests, test plans and Stress Tests
59
+ - Read results and OCPP logs
60
+ - Manage projects, tags and API keys
72
61
 
73
- **Stress tests**: `run_stress_test`, `list_stress_tests`, `get_stress_test`, `stop_stress_test`
62
+ Some things still need the [portal](https://app.timetick.io): billing, resetting a password, and security profiles (Basic Auth or certificates towards a CSMS).
74
63
 
75
- **Test plans**: `list_test_plans`, `get_test_plan`, `create_test_plan`, `update_test_plan`, `launch_test_plan`, `stop_test_plan`, `delete_test_plan`
64
+ ## Projects and trial
76
65
 
77
- Lists return 20 rows per page. Pass `page` and `pageSize` for the rest; every reply reports the total.
66
+ Your first project gets the free trial, which starts when you create it. Any further project needs payment details, which you add in the portal.
78
67
 
79
- ## Several accounts
68
+ A project with no active plan is read-only. If you started onboarding in the portal and didn't finish, ask the agent to start the trial.
80
69
 
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.
70
+ If you have several projects, tell the agent which one to use.
82
71
 
83
- ## Projects
84
-
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 |
94
-
95
- Pass `project` to a tool to target a different project for that call alone.
96
-
97
- ## Configuration
72
+ ## Read-only mode
98
73
 
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` |
74
+ Set `TIMETICK_MCP_READONLY=1` and the agent can read your data but not change it. You can still sign in and out.
105
75
 
106
- ## Read-only mode
76
+ ## Help
107
77
 
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.
78
+ For questions, write to support@timetick.io.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@timetick/mcp",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "Model Context Protocol (MCP) server for Timetick (https://app.timetick.io) platform",
5
5
  "license": "AGPL-3.0-or-later",
6
6
  "author": "Timetick <support@timetick.io>",