@syntholoc/mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,44 +1,73 @@
 # @syntholoc/mcp
 
-MCP-сервер Syntholoc — позволяет пользоваться платформой локализации прямо из Claude Code.
-Часть плана [`docs/CLAUDE_CODE_INTEGRATION_PLAN.md`](../../docs/CLAUDE_CODE_INTEGRATION_PLAN.md) (Фаза 1, stdio + API-ключ).
+The [Syntholoc](https://syntholoc.com) MCP server — manage AI localization and
+translation straight from [Claude Code](https://claude.com/claude-code) (or any
+MCP client), without leaving your editor.
 
-## Запуск
+## Add to Claude Code
 
 ```bash
-SYNTHOLOC_API_URL=http://localhost:4000/graphql \
-SYNTHOLOC_API_KEY=<ваш ключ> \
-bun run apps/mcp/src/index.ts
+claude mcp add --transport stdio syntholoc \
+  --env SYNTHOLOC_API_KEY=<your-api-key> \
+  -- bunx @syntholoc/mcp
 ```
 
-`SYNTHOLOC_API_KEY` отправляется заголовком `x-api-key`; организация выводится из метаданных
-ключа на сервере. `get_config` работает и без ключа (публичный `appInfo`).
+Get an API key from your Syntholoc dashboard. It is sent as the `x-api-key`
+header; the active organization is resolved from the key server-side and is
+never passed as a tool argument.
 
-## Подключение к Claude Code
+### Environment variables
 
-```bash
-claude mcp add --transport stdio syntholoc \
-  --env SYNTHOLOC_API_KEY=<ваш ключ> \
-  --env SYNTHOLOC_API_URL=http://localhost:4000/graphql \
-  -- bun run /абсолютный/путь/apps/mcp/src/index.ts
+| Variable | Default | Description |
+|---|---|---|
+| `SYNTHOLOC_API_KEY` | – | Machine API key (`x-api-key`). Required for most tools. |
+| `SYNTHOLOC_API_URL` | `https://api.syntholoc.com/graphql` | GraphQL endpoint. Override to target a self-hosted or local instance. |
+| `SYNTHOLOC_TOOL_SETS` | *(all)* | Comma-separated tool sets to load (`projects,keys,translations,qa,glossary,styleguides,tm,git,providers,jobs,analytics,locales,config`). Fewer tools = a more focused agent. |
+| `SYNTHOLOC_READ_ONLY` | `false` | Set `true` to expose only read-only tools (list/get) — safe exploration and onboarding. |
+| `SYNTHOLOC_TOOL_FILTER` | *(none)* | Comma-separated wildcard patterns matched against tool names (e.g. `list_*,get_*`). |
+
+> The remote (HTTP) transport accepts the same controls as request headers:
+> `syntholoc-tool-sets`, `syntholoc-read-only`, `syntholoc-tool-filter`. The hosted
+> endpoint is versioned at `/mcp/v1` (the legacy `/mcp` path still works).
+
+### Choosing an organization (hosted / OAuth)
+
+An OAuth token is per-user and may belong to several organizations. By default the
+earliest one is used. To pin a specific org, send the `syntholoc-org-id` header
+(verified against your membership). List the ids with the `list_organizations` tool
+or the `syntholoc://organizations` resource, then add it to your client config, e.g.:
+
+```json
+{
+  "mcpServers": {
+    "syntholoc": {
+      "type": "http",
+      "url": "https://api.syntholoc.com/mcp/v1",
+      "headers": { "syntholoc-org-id": "<org-id>" }
+    }
+  }
+}
 ```
 
-## Инструменты
+API-key (stdio) clients don't need this — the key is already scoped to one org.
+
+## What you can do
+
+Task-oriented tools across the whole platform: projects, locales, source keys,
+translation, QA, glossary, style guides, git integration, LLM providers, jobs,
+and analytics — plus MCP resources and prompts for common workflows.
 
-45 task-ориентированных инструментов по доменам: проекты, локали, ключи (`upsert_keys` для
-delta-синка), перевод (`translate_locale`/`translate_key` → `jobIds`), QA, глоссарий, style guides,
-git, провайдеры, джобы (`get_job`/`wait_for_job` — поллинг), аналитика. Плюс **ресурсы**
-(`syntholoc://config|projects|project/{id}`) и **промпты** (`localize_changed`, `review_locale`,
-`bootstrap_project`).
+Typical asks, one sentence each:
 
-### Порог батч-перевода (cost-оптимизация)
+- *"Translate the untranslated German strings and wait for it to finish."*
+- *"Show project progress and the QA score."*
+- *"Add these glossary terms and re-run QA on French."*
+- *"Export the Spanish locale."*
 
-`translate_locale` всегда переводит при вызове. Политику «копить до `maxBulkSize` или спросить»
-применяет клиент (навык/хук) для **проактивных** синков, а не сам инструмент — прямая просьба
-пользователя выполняется независимо от количества новых ключей. См. §8 плана.
+Translation runs asynchronously and returns a job id; a `wait_for_job` tool
+blocks until completion, so you can chain "translate → wait → export" in a
+single request.
 
-## Типы
+## License
 
-Типобезопасный GraphQL-клиент и операции — в общем пакете
-[`@syntholoc/sdk`](../../packages/sdk) (codegen из `apps/api/src/schema.gql`), который
-переиспользуют и MCP-сервер, и CLI. Инструменты импортируют операции и `GraphQLClient` из SDK.
+MIT

package/dist/build-server.d.ts

@@ -1,11 +1,33 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { GraphQLClient } from '@syntholoc/sdk';
 
+/**
+ * Server-side tool-filtering options, mirroring Crowdin's `crowdin-tool-sets` /
+ * `crowdin-read-only` / `crowdin-tool-filter` headers. Applied before the tool
+ * list is returned so the agent only sees a focused surface.
+ */
+interface ToolFilterOptions {
+    /** Tool-set names to load (see TOOL_SET_NAMES). Empty / undefined / ['all'] loads everything. */
+    toolSets?: string[];
+    /** When true, only read-only tools (annotations.readOnlyHint) are exposed. */
+    readOnly?: boolean;
+    /** Wildcard patterns matched against tool names (e.g. "list_*", "project*"). */
+    toolFilter?: string[];
+}
+/** Parses a comma-separated header/env value into a trimmed, non-empty string list. */
+declare function parseList(value: string | undefined | null): string[] | undefined;
+
+/** The valid tool-set names clients may request. */
+declare const TOOL_SET_NAMES: string[];
+
 /**
  * Builds a fully-configured Syntholoc MCP server (tools + resources + prompts)
  * bound to the given GraphQL client. Shared by the stdio entrypoint and the
  * NestJS remote `/mcp` (Streamable HTTP) endpoint.
+ *
+ * `opts` optionally narrows the exposed tool surface (tool sets, read-only mode,
+ * name-pattern filter) so the agent sees only what a given client needs.
  */
-declare function buildMcpServer(gql: GraphQLClient): McpServer;
+declare function buildMcpServer(gql: GraphQLClient, opts?: ToolFilterOptions): McpServer;
 
-export { buildMcpServer };
+export { TOOL_SET_NAMES, type ToolFilterOptions, buildMcpServer, parseList };

package/dist/build-server.js

@@ -1,7 +1,10 @@
 import {
-  buildMcpServer
-} from "./chunk-N4PXYXAP.js";
+  TOOL_SET_NAMES,
+  buildMcpServer,
+  parseList
+} from "./chunk-QOVGANRN.js";
 export {
-  buildMcpServer
+  TOOL_SET_NAMES,
+  buildMcpServer,
+  parseList
 };
-//# sourceMappingURL=build-server.js.map