@telkit/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PEKKA AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# @telkit/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Purpose
+
+Telkit's MCP server (Model Context Protocol) for developers and coding agents such as Claude Code
+and Cursor. It helps you set up and test a Telkit integration: your agent reads the guides, looks up
+any operation of the API with its fields and error codes, sends a test SMS or e-mail, and reads
+the message, the event log, the API log and your webhooks. It speaks the API under `/v2` through
+`@telkit/sdk` 1.0, where an operation has one name everywhere: `sms.send` is `POST /v2/sms` and
+`telkit.sms.send(…)`.
+
+**Test keys only.** The server starts only with a test key (`tk_test_…`); any other key stops it
+before anything happens. A test key's sends are simulated and free, so nothing reaches a real
+recipient and nothing costs. One exception, Telkit's own rule for every test key: an SMS to the
+confirmed mobile number of a member of the company, or an e-mail to a member's sign-in address, also
+arrives for real and free, at most 5 SMS units (a long SMS counts each of its parts) and 5 e-mails a
+day. An e-mail's answer says `testCopy: true` when a recipient is such a member, and it stays
+`true` when the day's limit stops the copy; an SMS answer has no such field.
+
+Create a test key in Telkit's dashboard under Developers › API keys. Give it the scopes the tools
+need: `sms:send`, `sms:read`, `email:send`, `email:read`, `events:read`, `webhooks:manage` and
+`usage:read`.
+
+## Connect it
+
+The server runs over stdio with `npx @telkit/mcp` (Node 20 or newer) or `bunx @telkit/mcp`, and
+reads the key from `TELKIT_API_KEY`.
+
+**Claude Code:**
+
+```sh
+claude mcp add --env TELKIT_API_KEY=tk_test_… --transport stdio telkit -- npx -y @telkit/mcp
+```
+
+**Cursor** (`.cursor/mcp.json` in the project, or `~/.cursor/mcp.json`):
+
+```json
+{
+	"mcpServers": {
+		"telkit": {
+			"command": "npx",
+			"args": ["-y", "@telkit/mcp"],
+			"env": { "TELKIT_API_KEY": "tk_test_…" }
+		}
+	}
+}
+```
+
+`TELKIT_API_URL` points the server at another API origin than `https://api.telkit.no` (a proxy, a
+local server).
+
+## Tools
+
+Look up (bundled with the package, no network and no key needed):
+
+| Tool | What it answers |
+|---|---|
+| `find_guide` | The developer guides as markdown (Norwegian): a search, or one guide in full by its slug |
+| `describe_operation` | One operation by its name (`sms.send`, `tools.smsCampaigns.create`), its method and path (`POST /v2/sms`) or words: the SDK call, input fields, answer, error codes with their sentences. The core of the API comes first, then the rest of `/v2`, then the tools under `/v2/tools` |
+| `describe_event` | The events webhooks deliver and the event log keeps, with each one's `data` fields |
+
+Test (each one call of `@telkit/sdk` with your test key):
+
+| Tool | Calls |
+|---|---|
+| `send_test_sms` | `telkit.sms.send`, `POST /v2/sms` |
+| `send_test_email` | `telkit.email.send`, `POST /v2/email` |
+| `get_message` | `telkit.sms.get` or `telkit.email.get`, `GET /v2/sms/{id}`, `GET /v2/email/{id}` |
+| `list_events` | `telkit.events.list`, `GET /v2/events` |
+| `list_api_requests` | `telkit.account.requests.list`, `GET /v2/account/requests` |
+| `set_up_webhook` | `telkit.webhooks.create`, `POST /v2/webhooks` |
+| `list_webhooks` | `telkit.webhooks.list`, `GET /v2/webhooks` |
+| `send_test_event` | `telkit.webhooks.test` to one webhook (`POST /v2/webhooks/{id}/test`), or `telkit.events.sendTest` to the whole application (`POST /v2/events/test`) |
+
+A call answers `{ data, error }`. The tool result is the `data` as JSON; an error comes back as a
+tool result marked as an error, with the API's `code` and `message`, the HTTP status, `retryable`,
+`meta` and the `requestId` (and `issues` when the input could not be read). A call whose answer
+never arrived is `network_error`, with `commit: "unknown"` and the `idempotencyKey` when it may
+have acted.
+
+## Invariants
+
+- **Test keys only, checked at start** (`src/environment.ts`) and again where the SDK client is
+  made (`telkitClientOf`), so a program that builds the server itself is held to it too: the server
+  mints test-mode keys
+  under `tk_test_` and live keys and client tokens under `tk_` (`backend/server/src/access.ts`).
+  The check is a product rule, not the wall: a test key cannot act live on the server either.
+- **One SDK call per test tool**, through `@telkit/sdk` 1.0 (`src/server.ts`), never hand-written
+  HTTP. Every call sends `telkit-client: telkit-mcp/<version>`, so the API log names this server.
+- **The key never shows in an answer**: the server is given the key it started with and takes it
+  out of every tool result, whatever the API answered; what the runtime threw (`cause`) is left
+  out of an error. The one secret an answer does hold is a new webhook's signing secret from
+  `set_up_webhook`, which the API shows once and the developer must store.
+- **The catalog is bundled and generated** (`src/generated/catalog.ts`, by `scripts/catalog.ts`),
+  from these sources, and nothing in it is written by hand:
+  - the operations, their fields, error codes and events from the two `/v2` OpenAPI documents the
+    SDK's `generate` writes (`client/sdk/src/generated/v2/openapi.json` and `tools/openapi.json`),
+    held to the server's committed snapshots (`backend/server/api-snapshots/api.json` and
+    `tools.json`): the script stops when a document and its snapshot name different operations,
+    routes or codes, and `tests/unit/server.test.ts` holds the catalog to the snapshots. An
+    operation's name is its id. An upload door is one operation, as the SDK calls it;
+  - an idempotency key, `identity`, a list and the file fields per operation from the SDK's own
+    generated facts (`client/sdk/src/generated/v2/facts.ts`), the table `createTelkit()` is built
+    from;
+  - the order from the docs' reference (`coreOperations` in
+    `client/web/src/features/api-docs/reference-groups.ts`, read as text): the core of the API in
+    the contract's order, then the rest of `/v2` by building block, then the tools;
+  - the error sentences from the server's own catalog (checked against the documents'
+    descriptions; a code the server's catalog lacks takes its sentence from the descriptions, and
+    22 framework upload and webhook codes have none: at run time the API's own `message` is what a
+    tool shows);
+  - the guides from `guides/llms.txt` and `guides/llms-full.txt`, the web app's two files for
+    agents, kept in this package so `generate` needs no running web app (the typecheck's generate
+    step and the publish build run it as it is).
+
+  Bundled, a lookup answers offline and describes the API version the bundled SDK calls.
+  `bun run --cwd client/mcp generate` runs after `api:snapshot` (the typecheck runs it too). After
+  the docs change, fetch the guides again from a running web app and commit the two files:
+  `bun run --cwd client/mcp generate --docs-origin http://localhost:10665`. A guide that calls the
+  SDK by a name the catalog lacks turns `tests/unit/server.test.ts` red, and so does a page of the
+  docs (`client/web/src/content/docs/entries.ts`) without a bundled guide: the guides are stale.
+- **`mcpVersion`** in `src/server.ts` equals `version` in `package.json`
+  (`tests/unit/server.test.ts`).
+
+## How to test
+
+`bun run test client/mcp/tests/unit` (no network). The journey against the running dev API
+(`http://localhost:10660`, it mints its own test key as the dev person `ada`):
+`bun run test:integration client/mcp/tests/integration`. Build: `bun run --cwd client/mcp build`
+(it runs the SDK's and this package's `generate` first),
+then `TELKIT_API_KEY=tk_test_… node client/mcp/dist/main.js`.
+
+## Publish a release
+
+The workspace's `package.json` stays private; npm receives only the build in `dist/` (`main.js`
+with `@telkit/sdk` and the catalog bundled, the MCP SDK and zod as dependencies). Raise `version`
+in `package.json` and `mcpVersion` in `src/server.ts` together, commit, then
+`bun scripts/sdk-publish.ts --commit <the released commit> --package mcp` from the repository root
+(add `--publish` to publish), as for `@telkit/sdk` (`client/sdk/README.md`, «Publish a release»).