@iconicompany/imcp 0.0.0-stage → 0.1.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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Iconicompany
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,106 @@
1
- # Temporary Holding Version
1
+ # @iconicompany/imcp
2
2
 
3
- 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.
3
+ MCP-сервер модуля платформы одной функцией. Для агентов и сервисов, у которых нет заготовки модуля:
4
+
5
+ - вход по токену ZITADEL: подпись, издатель, аудитория, роль проекта;
6
+ - регистрация инструментов со схемой zod, кто зовёт — из токена;
7
+ - `/health`, карточка сервера (SEP-1649) и метаданные ресурса (RFC 9728);
8
+ - строка журнала JSON на каждый вызов инструмента с `request_id` и `trace_id`.
9
+
10
+ Пакет — исходники TypeScript без сборки, нужен Bun. Окружение пакет не читает, всё передаётся параметрами.
11
+
12
+ ```sh
13
+ bun add @iconicompany/imcp zod
14
+ ```
15
+
16
+ ```ts
17
+ import { createMcpService, defineTool, ToolRefusal } from "@iconicompany/imcp";
18
+ import { z } from "zod";
19
+
20
+ const mcp = createMcpService({
21
+ name: "iexample",
22
+ version: "0.1.0",
23
+ title: "Пример",
24
+ origin: "https://iconicompany.com", // из конфига, не из Host
25
+ basePath: "/iexample",
26
+ auth: {
27
+ issuer: "https://id.iconicompany.com",
28
+ audiences: ["<id проекта ZITADEL>"],
29
+ role: "iexample:agent", // без роли — 403
30
+ },
31
+ tools: [
32
+ defineTool({
33
+ name: "order_status",
34
+ description: "Статус заказа организации вызывающего",
35
+ input: z.object({ orderId: z.string() }),
36
+ readOnly: true,
37
+ handler: async ({ orderId }, { caller }) => {
38
+ const order = await orders.find(caller.orgId, orderId);
39
+ if (!order) throw new ToolRefusal("Заказ не найден");
40
+ return { status: order.status }; // объект уходит JSON-текстом
41
+ },
42
+ }),
43
+ ],
44
+ });
45
+
46
+ // Bun.serve
47
+ Bun.serve({ routes: Object.fromEntries(mcp.paths.all.map((p) => [p, mcp.fetch])) });
48
+ // Elysia
49
+ for (const p of mcp.paths.all) app.all(p, ({ request }) => mcp.fetch(request));
50
+ ```
51
+
52
+ ## Адреса
53
+
54
+ | Путь | Вход | Что |
55
+ | ---------------------------------------------------- | ----- | -------------------------------------- |
56
+ | `/iexample/mcp` | токен | MCP, Streamable HTTP |
57
+ | `/iexample/health` | нет | `{ ok, name, version }` |
58
+ | `/iexample/.well-known/mcp/server-card.json` | нет | карточка сервера |
59
+ | `/.well-known/oauth-protected-resource/iexample/mcp` | нет | метаданные ресурса (и под `/iexample`) |
60
+
61
+ ## Вход
62
+
63
+ - Нет токена или он не принят — 401 с `WWW-Authenticate: Bearer resource_metadata="…"`: по нему клиент MCP
64
+ находит сервер авторизации. Причина наружу одна, без подсказки, что именно не сошлось.
65
+ - Аудитория обязательна: без неё прошёл бы токен любого приложения того же ZITADEL.
66
+ - `audiences` — id проектов ZITADEL. Роли читаются только из `urn:zitadel:iam:org:project:<id>:roles` этих
67
+ проектов: общий клейм и роли чужих проектов сервис не открывают. Нет роли `auth.role` — 403 `insufficient_scope`.
68
+ - Метаданные ресурса просят scope `urn:zitadel:iam:org:project:id:<id>:aud`: без него ZITADEL не впишет
69
+ проект в аудиторию.
70
+ - Токен — JWT: у приложения ZITADEL тип токена «JWT», непрозрачный проверить нечем.
71
+
72
+ ## Инструменты
73
+
74
+ `handler(args, { caller, headers })`:
75
+
76
+ - `caller` — `sub`, `clientId`, `roles`, `orgId`, `orgName`, `email`, `claims`. Человека и организацию
77
+ инструмент берёт отсюда, а не из аргументов: аргументы выбирает модель.
78
+ - `headers` — заголовки запроса; `x-request-id` и `traceparent` передавайте в вызовы соседей.
79
+ - Ответ: строка — текстом, объект — JSON, `CallToolResult` — как есть. Пустой строки не бывает.
80
+ - `throw new ToolRefusal("текст")` — отказ модели с этим текстом. Любая другая ошибка уходит модели общим
81
+ текстом, в журнал — только её класс (`internal: Error`): в сообщениях бывают персональные данные.
82
+ - `role` у инструмента — инструмент виден только с этой ролью.
83
+
84
+ ## Журнал
85
+
86
+ Строка JSON в stdout на вызов (`log` заменяет приёмник):
87
+
88
+ ```json
89
+ {
90
+ "msg": "mcp tool call",
91
+ "tool": "order_status",
92
+ "ok": true,
93
+ "ms": 12,
94
+ "sub": "…",
95
+ "client_id": "…",
96
+ "org_id": "…",
97
+ "request_id": "…",
98
+ "trace_id": "…"
99
+ }
100
+ ```
101
+
102
+ Аргументов в журнале нет: в них бывают персональные данные. Сбой приёмника журнала исход вызова не меняет.
103
+
104
+ ## Чего нет
105
+
106
+ A2A — пока нет.
package/package.json CHANGED
@@ -1,6 +1,46 @@
1
1
  {
2
2
  "name": "@iconicompany/imcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "MCP server for platform modules in one call: ZITADEL bearer (audience, project role), tools, /health, server card, tool call log",
5
+ "keywords": [
6
+ "bun",
7
+ "mcp",
8
+ "model-context-protocol",
9
+ "zitadel"
10
+ ],
11
+ "license": "MIT",
12
+ "repository": {
13
+ "type": "git",
14
+ "url": "git+https://github.com/iconicompany/imcp.git"
15
+ },
16
+ "files": [
17
+ "src"
18
+ ],
19
+ "type": "module",
20
+ "sideEffects": false,
21
+ "exports": {
22
+ ".": "./src/index.ts"
23
+ },
24
+ "publishConfig": {
25
+ "access": "public"
26
+ },
27
+ "scripts": {
28
+ "format": "oxfmt --write .",
29
+ "format:check": "oxfmt --check .",
30
+ "lint": "oxlint --deny-warnings .",
31
+ "type-check": "bunx tsgo --noEmit -p tsconfig.json",
32
+ "test": "bun test",
33
+ "validate": "bun run format:check && bun run lint && bun run type-check && bun run test"
34
+ },
35
+ "dependencies": {
36
+ "@modelcontextprotocol/server": "^2.4.0",
37
+ "jose": "^6.2.17",
38
+ "zod": "^4.6.7"
39
+ },
40
+ "devDependencies": {
41
+ "@types/bun": "^1.4.4",
42
+ "@typescript/native-preview": "^7.0.0-dev.20260707.2",
43
+ "oxfmt": "^0.79.0",
44
+ "oxlint": "^1.94.0"
45
+ }
46
+ }
package/src/bearer.ts ADDED
@@ -0,0 +1,88 @@
1
+ import { createRemoteJWKSet, jwtVerify, type JWTPayload, type JWTVerifyGetKey } from "jose";
2
+
3
+ /** Вход по токену ZITADEL: подпись, издатель, аудитория. Роль проекта проверяет сервис. */
4
+ export interface ZitadelAuthOptions {
5
+ /** Издатель без хвостового слэша: `https://id.example.com`. */
6
+ issuer: string;
7
+ /** Id проектов ZITADEL: токен обязан назвать один из них аудиторией, роли берутся из них же. Пустой список запрещён. */
8
+ audiences: readonly string[];
9
+ /** Роль проекта, без которой вход закрыт (403). Не задана — хватает аудитории. */
10
+ role?: string;
11
+ /** Откуда ключи; по умолчанию `<issuer>/oauth/v2/keys`. */
12
+ jwksUrl?: string;
13
+ /** Готовый набор ключей — для тестов. */
14
+ keys?: JWTVerifyGetKey;
15
+ /** Серверы авторизации для клиента MCP (RFC 9728); по умолчанию — издатель. */
16
+ authorizationServers?: string[];
17
+ }
18
+
19
+ /** Кто зовёт: из проверенного токена, не из аргументов инструмента. */
20
+ export interface Caller {
21
+ sub: string;
22
+ /** Клиент, которому выдан токен (`azp`/`client_id`). */
23
+ clientId: string;
24
+ /** Роли проекта ZITADEL из токена. */
25
+ roles: string[];
26
+ /** Организация человека: `urn:zitadel:iam:user:resourceowner:id`/`:name`. */
27
+ orgId: string | null;
28
+ orgName: string | null;
29
+ email: string | null;
30
+ claims: JWTPayload;
31
+ }
32
+
33
+ const CLOCK_TOLERANCE_SECONDS = 30;
34
+
35
+ const keysOf = (raw: unknown): string[] =>
36
+ Array.isArray(raw)
37
+ ? raw.filter((r): r is string => typeof r === "string")
38
+ : raw && typeof raw === "object"
39
+ ? Object.keys(raw)
40
+ : [];
41
+
42
+ /**
43
+ * Роли только проектов из `projects` — клейм `urn:zitadel:iam:org:project:<id>:roles`. Общий клейм и
44
+ * клеймы чужих проектов не читаются: роль `admin` другого проекта не открывает этот сервис.
45
+ */
46
+ export function rolesOf(claims: JWTPayload, projects: readonly string[]): string[] {
47
+ const roles = new Set<string>();
48
+ for (const id of projects)
49
+ for (const role of keysOf(claims[`urn:zitadel:iam:org:project:${id}:roles`])) roles.add(role);
50
+ return [...roles];
51
+ }
52
+
53
+ const text = (v: unknown) => (typeof v === "string" && v !== "" ? v : null);
54
+
55
+ export function createVerifier(options: ZitadelAuthOptions) {
56
+ // Без аудитории прошёл бы токен любого приложения того же ZITADEL: подпись у них общая.
57
+ if (options.audiences.length === 0) throw new Error("imcp: список аудиторий пуст");
58
+ const keys =
59
+ options.keys ??
60
+ createRemoteJWKSet(new URL(options.jwksUrl ?? `${options.issuer}/oauth/v2/keys`));
61
+
62
+ /** Caller или `null`: не JWT, не та подпись, издатель, аудитория или срок. */
63
+ return async (token: string): Promise<Caller | null> => {
64
+ // Непрозрачный токен проверить нечем: приложению ZITADEL нужен тип токена JWT.
65
+ if (token.split(".").length !== 3) return null;
66
+ let claims: JWTPayload;
67
+ try {
68
+ ({ payload: claims } = await jwtVerify(token, keys, {
69
+ issuer: options.issuer,
70
+ audience: [...options.audiences],
71
+ clockTolerance: CLOCK_TOLERANCE_SECONDS,
72
+ }));
73
+ } catch {
74
+ return null;
75
+ }
76
+ const sub = text(claims.sub);
77
+ if (!sub) return null;
78
+ return {
79
+ sub,
80
+ clientId: text(claims.azp) ?? text(claims.client_id) ?? "",
81
+ roles: rolesOf(claims, options.audiences),
82
+ orgId: text(claims["urn:zitadel:iam:user:resourceowner:id"]),
83
+ orgName: text(claims["urn:zitadel:iam:user:resourceowner:name"]),
84
+ email: text(claims.email),
85
+ claims,
86
+ };
87
+ };
88
+ }
package/src/index.ts ADDED
@@ -0,0 +1,10 @@
1
+ export { createMcpService, mcpPaths, type McpService, type McpServiceOptions } from "./service";
2
+ export {
3
+ defineTool,
4
+ ToolRefusal,
5
+ type ToolContext,
6
+ type ToolDefinition,
7
+ type ToolReturn,
8
+ } from "./tool";
9
+ export { createVerifier, rolesOf, type Caller, type ZitadelAuthOptions } from "./bearer";
10
+ export type { CallLine } from "./log";
package/src/log.ts ADDED
@@ -0,0 +1,42 @@
1
+ import type { CallToolResult } from "@modelcontextprotocol/server";
2
+
3
+ import type { Caller } from "./bearer";
4
+
5
+ /** Строка журнала на вызов инструмента. Аргументов нет: в них бывают персональные данные. */
6
+ export interface CallLine {
7
+ msg: "mcp tool call";
8
+ tool: string;
9
+ ok: boolean;
10
+ ms: number;
11
+ sub: string;
12
+ client_id: string;
13
+ org_id: string | null;
14
+ /** Причина отказа, до 200 знаков. */
15
+ reason?: string;
16
+ /** Ключи склейки с журналом вызывающего: `x-request-id` и trace id из `traceparent`. */
17
+ request_id: string | null;
18
+ trace_id: string | null;
19
+ }
20
+
21
+ export function callLine(
22
+ tool: string,
23
+ caller: Caller,
24
+ headers: Headers,
25
+ started: number,
26
+ result: CallToolResult,
27
+ reason?: string,
28
+ ): CallLine {
29
+ const traceparent = headers.get("traceparent") ?? "";
30
+ return {
31
+ msg: "mcp tool call",
32
+ tool,
33
+ ok: !result.isError,
34
+ ms: Math.round(performance.now() - started),
35
+ sub: caller.sub,
36
+ client_id: caller.clientId,
37
+ org_id: caller.orgId,
38
+ ...(reason !== undefined && { reason: reason.slice(0, 200) }),
39
+ request_id: headers.get("x-request-id"),
40
+ trace_id: /^[\da-f]{2}-([\da-f]{32})-/u.exec(traceparent)?.[1] ?? null,
41
+ };
42
+ }
package/src/service.ts ADDED
@@ -0,0 +1,232 @@
1
+ import {
2
+ createMcpHandler,
3
+ LATEST_PROTOCOL_VERSION,
4
+ McpServer,
5
+ type AuthInfo,
6
+ } from "@modelcontextprotocol/server";
7
+
8
+ import { createVerifier, type Caller, type ZitadelAuthOptions } from "./bearer";
9
+ import { callLine, type CallLine } from "./log";
10
+ import { isRefusal, refusalResult, toResult, type ToolDefinition } from "./tool";
11
+
12
+ export interface McpServiceOptions {
13
+ /** Имя сервера в протоколе и карточке: имя модуля (`iexample`). */
14
+ name: string;
15
+ version: string;
16
+ title?: string;
17
+ description?: string;
18
+ /** Внешний адрес — только origin: `https://iconicompany.com`. Из конфига, не из Host. */
19
+ origin: string;
20
+ /** Префикс модуля: `/iexample`; пустой — модуль на корне. */
21
+ basePath: string;
22
+ /** Адрес MCP под префиксом; по умолчанию `mcp` → `/iexample/mcp`. */
23
+ mcpPath?: string;
24
+ auth: ZitadelAuthOptions;
25
+ // Инструменты разных схем: тип аргументов проверен в defineTool.
26
+ // oxlint-disable-next-line no-explicit-any
27
+ tools: ToolDefinition<any>[];
28
+ /** Журнал вызовов инструментов; по умолчанию — строка JSON в stdout. */
29
+ log?: (line: CallLine) => void;
30
+ }
31
+
32
+ const CORS: Record<string, string> = {
33
+ "access-control-allow-origin": "*",
34
+ "access-control-allow-methods": "GET, POST, DELETE, OPTIONS",
35
+ "access-control-allow-headers":
36
+ "Authorization, Content-Type, Accept, Mcp-Protocol-Version, Mcp-Session-Id, Mcp-Method, Mcp-Name, Traceparent, X-Request-Id",
37
+ "access-control-expose-headers": "WWW-Authenticate, Mcp-Session-Id",
38
+ };
39
+
40
+ const clean = (p: string) => {
41
+ const t = p.trim().replace(/\/+$/, "");
42
+ return t && !t.startsWith("/") ? `/${t}` : t;
43
+ };
44
+
45
+ function originOf(raw: string): string {
46
+ let url: URL;
47
+ try {
48
+ url = new URL(raw);
49
+ } catch {
50
+ // Значение в сообщение не идёт: в нём бывает логин:пароль.
51
+ throw new Error("imcp: origin — не URL");
52
+ }
53
+ if (url.protocol !== "https:" && url.protocol !== "http:")
54
+ throw new Error("imcp: origin — не http(s)");
55
+ return url.origin;
56
+ }
57
+
58
+ /** Адреса сервиса: MCP, здоровье, карточка (SEP-1649), метаданные ресурса (RFC 9728 §3). */
59
+ export function mcpPaths(o: Pick<McpServiceOptions, "basePath" | "mcpPath">) {
60
+ const base = clean(o.basePath);
61
+ const rel = o.mcpPath?.trim() || "mcp";
62
+ const mcp = clean(rel.startsWith("/") ? rel : `${base}/${rel}`);
63
+ const metadata = `/.well-known/oauth-protected-resource${mcp}`;
64
+ return {
65
+ mcp,
66
+ health: `${base}/health`,
67
+ card: `${base}/.well-known/mcp/server-card.json`,
68
+ metadata,
69
+ metadataPaths: [...new Set([metadata, `${base}${metadata}`])],
70
+ };
71
+ }
72
+
73
+ const json = (body: unknown, status = 200, headers: Record<string, string> = {}) =>
74
+ new Response(JSON.stringify(body), {
75
+ status,
76
+ headers: { "content-type": "application/json; charset=utf-8", ...CORS, ...headers },
77
+ });
78
+
79
+ /**
80
+ * MCP-сервер модуля одной функцией: вход по токену ZITADEL (аудитория и роль проекта), инструменты,
81
+ * `/health`, карточка сервера и метаданные ресурса, строка журнала на каждый вызов инструмента.
82
+ * Возвращает fetch-обработчик: его монтируют на `paths.all` в `Bun.serve` или Elysia (`.mount`).
83
+ */
84
+ export function createMcpService(options: McpServiceOptions) {
85
+ const origin = originOf(options.origin);
86
+ const paths = mcpPaths(options);
87
+ const verify = createVerifier(options.auth);
88
+ const sink = options.log ?? ((line: CallLine) => console.log(JSON.stringify(line)));
89
+ // Сбой журнала не меняет исход вызова: иначе удачная запись ушла бы модели ошибкой и повторилась.
90
+ const log = (line: CallLine) => {
91
+ try {
92
+ sink(line);
93
+ } catch {
94
+ // журнал недоступен — вызов уже состоялся
95
+ }
96
+ };
97
+ const serverInfo = {
98
+ name: options.name,
99
+ version: options.version,
100
+ ...(options.title && { title: options.title }),
101
+ };
102
+ const metadataUrl = `${origin}${paths.metadata}`;
103
+
104
+ const card = {
105
+ $schema: "https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json",
106
+ version: "1.0",
107
+ protocolVersion: LATEST_PROTOCOL_VERSION,
108
+ serverInfo,
109
+ ...(options.description && { description: options.description }),
110
+ transport: { type: "streamable-http", url: `${origin}${paths.mcp}` },
111
+ capabilities: { tools: { listChanged: false } },
112
+ authentication: { required: true, schemes: ["oauth2"], resourceMetadata: metadataUrl },
113
+ };
114
+ const metadata = {
115
+ resource: `${origin}${paths.mcp}`,
116
+ authorization_servers: options.auth.authorizationServers ?? [options.auth.issuer],
117
+ // Без `…:project:id:<id>:aud` ZITADEL не впишет проект в aud, и токен клиента не пройдёт.
118
+ scopes_supported: [
119
+ "openid",
120
+ "profile",
121
+ "email",
122
+ "urn:zitadel:iam:org:projects:roles",
123
+ ...options.auth.audiences.map((id) => `urn:zitadel:iam:org:project:id:${id}:aud`),
124
+ ],
125
+ bearer_methods_supported: ["header"],
126
+ };
127
+
128
+ const mcp = createMcpHandler(({ authInfo, requestInfo }) => {
129
+ const caller = authInfo?.extra?.caller as Caller;
130
+ const headers = requestInfo?.headers ?? new Headers();
131
+ const server = new McpServer(serverInfo);
132
+ for (const tool of options.tools) {
133
+ if (tool.role && !caller.roles.includes(tool.role)) continue;
134
+ server.registerTool(
135
+ tool.name,
136
+ {
137
+ ...(tool.title && { title: tool.title }),
138
+ description: tool.description,
139
+ inputSchema: tool.input,
140
+ ...(tool.readOnly !== undefined && { annotations: { readOnlyHint: tool.readOnly } }),
141
+ },
142
+ async (args: unknown) => {
143
+ const started = performance.now();
144
+ try {
145
+ const result = toResult(await tool.handler(args, { caller, headers }));
146
+ log(callLine(tool.name, caller, headers, started, result));
147
+ return result;
148
+ } catch (error) {
149
+ // Отказ — текстом модели. Чужая ошибка — общим текстом, в журнал только её класс:
150
+ // в сообщении бывают значения аргументов и персональные данные.
151
+ const refusal = isRefusal(error);
152
+ const reason = refusal
153
+ ? error.message
154
+ : `internal: ${error instanceof Error ? error.name : typeof error}`;
155
+ const result = refusalResult(
156
+ refusal ? error.message : "Внутренняя ошибка инструмента.",
157
+ );
158
+ log(callLine(tool.name, caller, headers, started, result, reason));
159
+ return result;
160
+ }
161
+ },
162
+ );
163
+ }
164
+ return server;
165
+ });
166
+
167
+ // В заголовке только код: кириллица в WWW-Authenticate превращает ответ в 500. Текст — телом.
168
+ // Без токена — голый вызов без кода ошибки (RFC 6750 §3.1): клиент начинает вход, а не падает.
169
+ const challenge = (status: 401 | 403, error: string | null, description: string) =>
170
+ json(
171
+ error ? { error, error_description: description } : { error_description: description },
172
+ status,
173
+ {
174
+ "www-authenticate": `Bearer resource_metadata="${metadataUrl}"${error ? `, error="${error}"` : ""}`,
175
+ },
176
+ );
177
+
178
+ async function serveMcp(request: Request): Promise<Response> {
179
+ const header = request.headers.get("authorization") ?? "";
180
+ const token = /^Bearer\s+/i.test(header) ? header.replace(/^Bearer\s+/i, "").trim() : "";
181
+ if (!token) return challenge(401, null, "нужен токен: Authorization: Bearer <token>");
182
+ const caller = await verify(token);
183
+ // Одна причина наружу: что именно не сошлось, перебору не подсказываем.
184
+ if (!caller)
185
+ return challenge(
186
+ 401,
187
+ "invalid_token",
188
+ "токен не принят: подпись, издатель, аудитория или срок",
189
+ );
190
+ const role = options.auth.role;
191
+ if (role && !caller.roles.includes(role))
192
+ return challenge(403, "insufficient_scope", `нет роли проекта ${role}`);
193
+ const authInfo: AuthInfo = {
194
+ token,
195
+ clientId: caller.clientId,
196
+ scopes:
197
+ typeof caller.claims.scope === "string"
198
+ ? caller.claims.scope.split(" ").filter(Boolean)
199
+ : [],
200
+ ...(typeof caller.claims.exp === "number" && { expiresAt: caller.claims.exp }),
201
+ extra: { caller },
202
+ };
203
+ const response = await mcp.fetch(request, { authInfo });
204
+ const headers = new Headers(response.headers);
205
+ for (const [k, v] of Object.entries(CORS)) if (!headers.has(k)) headers.set(k, v);
206
+ return new Response(response.body, { status: response.status, headers });
207
+ }
208
+
209
+ const publicDoc = (body: unknown) => json(body, 200, { "cache-control": "public, max-age=300" });
210
+
211
+ async function fetch(request: Request): Promise<Response> {
212
+ const path = clean(new URL(request.url).pathname);
213
+ if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: CORS });
214
+ if (path === paths.mcp) return serveMcp(request);
215
+ if (request.method !== "GET" && request.method !== "HEAD")
216
+ return json({ error: "method_not_allowed" }, 405);
217
+ if (path === paths.health)
218
+ return json({ ok: true, name: options.name, version: options.version });
219
+ if (path === paths.card) return publicDoc(card);
220
+ if (paths.metadataPaths.includes(path)) return publicDoc(metadata);
221
+ return json({ error: "not_found" }, 404);
222
+ }
223
+
224
+ return {
225
+ fetch,
226
+ paths: { ...paths, all: [paths.mcp, paths.health, paths.card, ...paths.metadataPaths] },
227
+ card,
228
+ close: () => mcp.close(),
229
+ };
230
+ }
231
+
232
+ export type McpService = ReturnType<typeof createMcpService>;
package/src/tool.ts ADDED
@@ -0,0 +1,61 @@
1
+ import type { CallToolResult } from "@modelcontextprotocol/server";
2
+ import type { z } from "zod";
3
+
4
+ import type { Caller } from "./bearer";
5
+
6
+ /** Что видит инструмент: кто зовёт и заголовки запроса (`x-request-id`, `traceparent` — для вызовов соседей). */
7
+ export interface ToolContext {
8
+ caller: Caller;
9
+ headers: Headers;
10
+ }
11
+
12
+ /** Отказ инструмента: текст уходит модели как `isError`, в журнал — причиной. */
13
+ export class ToolRefusal extends Error {
14
+ override name = "ToolRefusal";
15
+ }
16
+
17
+ /** По имени, не instanceof: у продукта и его зависимости бывают разные копии пакета. */
18
+ export const isRefusal = (e: unknown): e is Error => e instanceof Error && e.name === "ToolRefusal";
19
+
20
+ /** Строка — текстом, объект — JSON, `CallToolResult` — как есть. */
21
+ export type ToolReturn = string | CallToolResult | Record<string, unknown> | unknown[];
22
+
23
+ export interface ToolDefinition<S extends z.ZodObject = z.ZodObject> {
24
+ name: string;
25
+ title?: string;
26
+ description: string;
27
+ input: S;
28
+ /** Только чтение — подсказка клиенту (`readOnlyHint`). */
29
+ readOnly?: boolean;
30
+ /** Роль проекта сверх роли сервиса; без неё инструмента в списке нет. */
31
+ role?: string;
32
+ handler: (args: z.infer<S>, ctx: ToolContext) => Promise<ToolReturn> | ToolReturn;
33
+ }
34
+
35
+ /** Типизирует аргументы обработчика по схеме. */
36
+ export const defineTool = <S extends z.ZodObject>(tool: ToolDefinition<S>): ToolDefinition<S> =>
37
+ tool;
38
+
39
+ // Готовый результат — только если каждый элемент content с полем type: запись `{ content: ["…"] }` — данные.
40
+ const isCallToolResult = (v: unknown): v is CallToolResult => {
41
+ const content = (v as { content?: unknown } | null)?.content;
42
+ return (
43
+ Array.isArray(content) &&
44
+ content.every(
45
+ (c) => !!c && typeof c === "object" && typeof (c as { type?: unknown }).type === "string",
46
+ )
47
+ );
48
+ };
49
+
50
+ export function toResult(value: ToolReturn): CallToolResult {
51
+ if (isCallToolResult(value)) return value;
52
+ // Пустой ответ модель принимает за сбой: текст есть всегда.
53
+ const text = typeof value === "string" ? value : JSON.stringify(value);
54
+ return { content: [{ type: "text", text: text || "Готово." }] };
55
+ }
56
+
57
+ /** Отказ модели: пустой текст не превращается в «Готово.». */
58
+ export const refusalResult = (text: string): CallToolResult => ({
59
+ content: [{ type: "text", text: text || "Отказ." }],
60
+ isError: true,
61
+ });