Document MCP security and operations guidance

.changeset/green-readers-stare.md

@@ -0,0 +1,6 @@
+---
+"@typesensekit/mcp": patch
+"@typesensekit/cli": patch
+---
+
+Document scoped API key guidance, production MCP operations, and compatibility notes.

README.md

@@ -98,6 +98,9 @@ tsk skills claude-code
 tsk skills hermes
 ```
 
+For scoped key examples, production guidance, and the compatibility matrix, read
+[`docs/mcp-security.md`](./docs/mcp-security.md).
+
 ## API Coverage
 
 TypesenseKit covers the common Typesense administration and search surfaces, plus `api.call` for endpoints that are new, uncommon, or not yet wrapped.

docs/mcp-security.md

@@ -0,0 +1,110 @@
+# MCP Security and Operations
+
+TypesenseKit's MCP server defaults to read-only tools. Keep that default for
+assistant workflows unless the MCP client is running in a trusted operator-only
+environment.
+
+## API Key Scope
+
+Use the narrowest Typesense API key that supports the tools you plan to expose.
+Typesense supports per-action and per-collection key scopes. Its API key docs
+recommend avoiding bootstrap/admin keys in production and generating scoped keys
+for each application.
+
+Minimal search-only key:
+
+```json
+{
+  "description": "typesensekit-mcp-search",
+  "actions": ["documents:search"],
+  "collections": ["products"]
+}
+```
+
+Search plus document and collection metadata:
+
+```json
+{
+  "description": "typesensekit-mcp-read",
+  "actions": [
+    "documents:search",
+    "documents:get",
+    "documents:export",
+    "collections:get",
+    "collections:list",
+    "aliases:get",
+    "aliases:list",
+    "synonyms:get",
+    "synonyms:list",
+    "synonym_sets:get",
+    "synonym_sets:list",
+    "synonym_sets/items:get",
+    "synonym_sets/items:list",
+    "stopwords:get",
+    "stopwords:list",
+    "presets:get",
+    "presets:list",
+    "metrics.json:list",
+    "stats.json:list",
+    "debug:list"
+  ],
+  "collections": ["products"]
+}
+```
+
+Notes:
+
+- Do not use the bootstrap key or an admin key for assistant access.
+- Keep `TYPESENSEKIT_READ_ONLY` unset or set to `true` for normal MCP clients.
+- Set `TYPESENSEKIT_READ_ONLY=false` only for trusted maintenance sessions.
+- Do not expose `keys:*`, write actions, or wildcard `*` actions to agents.
+- Scope `collections` to concrete collection names or narrow regexes.
+- If user-specific filtering is required, generate scoped search keys from a
+  parent key that only has `documents:search`.
+
+## Environment
+
+Required:
+
+```sh
+TYPESENSE_URL=https://your-cluster.typesense.net
+TYPESENSE_API_KEY=your-scoped-api-key
+```
+
+Optional:
+
+```sh
+TYPESENSE_CONNECTION_TIMEOUT_SECONDS=5
+TYPESENSEKIT_READ_ONLY=true
+```
+
+## Production Guidance
+
+- Run the MCP server in read-only mode by default.
+- Prefer a dedicated API key per MCP deployment so it can be rotated without
+  impacting application traffic.
+- Set a short Typesense connection timeout for assistant workflows. Long
+  timeouts make tool calls harder to cancel and retry.
+- Apply rate limits at the MCP client, process supervisor, reverse proxy, or
+  container platform boundary. TypesenseKit does not currently enforce per-tool
+  rate limits inside the stdio server.
+- Capture process stdout/stderr from the supervisor. Tool results are returned to
+  the MCP client, and TypesenseKit redacts API keys, auth headers, cookies, and
+  generated key values from tool output and errors.
+- Treat `documents.export` as sensitive. It is read-only, but it can return a
+  large amount of data if the API key and collection scope allow it.
+
+## Compatibility
+
+| TypesenseKit MCP version | Typesense client | Typesense server guidance |
+| --- | --- | --- |
+| 1.1.x | `typesense` npm package `^3.0.6` | Built for the current Typesense Admin API surface and local development against Typesense 27.1. Includes v30 global synonym set operations. |
+
+TypesenseKit also exposes `api.call` when read-only mode is disabled, so newer
+Typesense endpoints can still be reached before a first-class operation is
+added. Keep `api.call` disabled for assistant-facing read-only deployments.
+
+## References
+
+- Typesense API keys: https://typesense.org/docs/30.2/api/api-keys.html
+- Typesense data access control: https://typesense.org/docs/guide/data-access-control.html

packages/mcp/README.md

@@ -9,4 +9,5 @@ TYPESENSE_URL=http://localhost:8108 TYPESENSE_API_KEY=xyz pnpm dlx @typesensekit
 
 Set `TYPESENSEKIT_READ_ONLY=false` to expose write/delete/admin tools.
 
-See the root README for client configuration and operation coverage.
+See the root README for client configuration, security guidance, and operation
+coverage.