@iconicompany/imcp 0.2.0 → 0.3.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/README.md CHANGED
@@ -86,6 +86,20 @@ for (const p of mcp.paths.all) app.all(p, ({ request }) => mcp.fetch(request));
86
86
  - `meta` — `_meta` инструмента в `tools/list`, ключ — обратный домен. Встроенный чат iagent берёт инструмент
87
87
  только с `meta: { "com.iconicompany.iagent/embed": true }` и `readOnly: true`.
88
88
 
89
+ ## Плагин агента
90
+
91
+ Указания агента модуля живут в репозитории модуля в формате плагина Claude Code (`agent/.claude-plugin/plugin.json`,
92
+ `agent/skills/*/SKILL.md`, `agent/.mcp.json`) и отдаются iagent по `GET <basePath>/agent/plugin.json`:
93
+
94
+ ```ts
95
+ plugin: loadPluginDir(`${import.meta.dir}/../agent`), // бинарник --compile: parsePlugin({ путь: текст }) из импортов файлов
96
+ ```
97
+
98
+ - `plugin.json`: `name`, `version` (semver, поднимать при любой правке текста), `description`, `roles` — роли проекта,
99
+ без которых ручка отвечает 403 (как роль инструмента). Без токена — 401.
100
+ - Ответ: `{ name, version, description, roles, mcp: { url }, skills: [{ name, description, body }] }`, `body` — текст
101
+ SKILL.md без frontmatter. Кривой плагин (нет skills, пустой skill, версия не semver) — исключение при старте.
102
+
89
103
  ## Журнал
90
104
 
91
105
  Строка JSON в stdout на вызов (`log` заменяет приёмник):
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@iconicompany/imcp",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "MCP server for platform modules in one call: ZITADEL bearer (audience, project role), tools, /health, server card, tool call log",
5
5
  "keywords": [
6
6
  "bun",
package/src/index.ts CHANGED
@@ -8,3 +8,4 @@ export {
8
8
  } from "./tool";
9
9
  export { createVerifier, rolesOf, type Caller, type ZitadelAuthOptions } from "./bearer";
10
10
  export type { CallLine } from "./log";
11
+ export { loadPluginDir, parsePlugin, type AgentPlugin } from "./plugin";
package/src/plugin.ts ADDED
@@ -0,0 +1,105 @@
1
+ import { existsSync, readdirSync, readFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+
4
+ /** Плагин агента модуля (формат Claude Code: `.claude-plugin/plugin.json`, `skills/*\/SKILL.md`, `.mcp.json`). */
5
+ export interface AgentPlugin {
6
+ name: string;
7
+ version: string;
8
+ description?: string;
9
+ /** Роли проекта, без которых плагин не отдаётся (как роль инструмента). */
10
+ roles: string[];
11
+ mcp?: { url: string };
12
+ skills: { name: string; description: string; body: string }[];
13
+ }
14
+
15
+ const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
16
+ const fail = (why: string): never => {
17
+ throw new Error(`imcp: плагин — ${why}`);
18
+ };
19
+
20
+ /** SKILL.md: frontmatter `name`, `description` и текст после него. */
21
+ function skillOf(path: string, text: string): AgentPlugin["skills"][number] {
22
+ const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
23
+ if (!m) return fail(`${path}: нет frontmatter`);
24
+ // Только однострочные значения: блок YAML (`>`, `|`) не разбираем — отказ, а не «>-» в описании.
25
+ const field = (key: string) => {
26
+ const value = new RegExp(`^${key}:[ \\t]*(.*)$`, "m").exec(m[1]!)?.[1]?.trim() ?? "";
27
+ if (/^[>|]/.test(value)) fail(`${path}: ${key} — блок YAML, нужна одна строка`);
28
+ const quoted = /^(["'])(.*)\1$/.exec(value);
29
+ return quoted ? quoted[2]! : value;
30
+ };
31
+ const skill = { name: field("name"), description: field("description"), body: m[2]!.trim() };
32
+ if (!skill.name || !skill.description || !skill.body)
33
+ fail(`${path}: пустые name, description или текст`);
34
+ return skill;
35
+ }
36
+
37
+ /** Файлы плагина (путь от его каталога → текст) → плагин. Кривой — исключение: модуль не стартует. */
38
+ export function parsePlugin(files: Record<string, string>): AgentPlugin {
39
+ const raw = files[".claude-plugin/plugin.json"] ?? fail("нет .claude-plugin/plugin.json");
40
+ let manifest: Record<string, unknown>;
41
+ try {
42
+ manifest = JSON.parse(raw) as Record<string, unknown>;
43
+ } catch {
44
+ return fail(".claude-plugin/plugin.json — не JSON");
45
+ }
46
+ const name = typeof manifest.name === "string" ? manifest.name : "";
47
+ const version = typeof manifest.version === "string" ? manifest.version : "";
48
+ if (!name) fail("нет name");
49
+ if (!SEMVER.test(version)) fail(`version «${version}» — не semver`);
50
+ // Роли обязательны: без них ручка отдала бы указания агента любому токену аудитории.
51
+ const roles = manifest.roles;
52
+ if (
53
+ !Array.isArray(roles) ||
54
+ roles.length === 0 ||
55
+ !roles.every((r) => typeof r === "string" && r !== "")
56
+ )
57
+ fail("roles — непустой список ролей проекта");
58
+ const skills = Object.keys(files)
59
+ .filter((p) => /^skills\/[^/]+\/SKILL\.md$/.test(p))
60
+ .sort()
61
+ .map((p) => skillOf(p, files[p]!));
62
+ if (skills.length === 0) fail("нет skills/*/SKILL.md");
63
+ const names = skills.map((k) => k.name);
64
+ const twice = names.find((n, i) => names.indexOf(n) !== i);
65
+ if (twice) fail(`skill ${twice} — дважды`);
66
+ let mcp: AgentPlugin["mcp"];
67
+ if (files[".mcp.json"]) {
68
+ let servers: Record<string, unknown>;
69
+ try {
70
+ servers = ((JSON.parse(files[".mcp.json"]) as { mcpServers?: Record<string, unknown> })
71
+ .mcpServers ?? {}) as Record<string, unknown>;
72
+ } catch {
73
+ return fail(".mcp.json — не JSON");
74
+ }
75
+ const url = Object.values(servers)
76
+ .map((v) => (v && typeof v === "object" ? (v as { url?: unknown }).url : undefined))
77
+ .find((u): u is string => typeof u === "string");
78
+ if (url) mcp = { url };
79
+ }
80
+ return {
81
+ name,
82
+ version,
83
+ ...(typeof manifest.description === "string" && { description: manifest.description }),
84
+ roles: roles as string[],
85
+ ...(mcp && { mcp }),
86
+ skills,
87
+ };
88
+ }
89
+
90
+ /** Каталог плагина на диске → плагин. В бинарнике `bun build --compile` каталога нет: там — `parsePlugin` с импортом файлов. */
91
+ export function loadPluginDir(dir: string): AgentPlugin {
92
+ // Только файлы плагина: скрипты и картинки skills не читаем, по ссылкам не ходим.
93
+ const files: Record<string, string> = {};
94
+ for (const path of [".claude-plugin/plugin.json", ".mcp.json"])
95
+ if (existsSync(join(dir, path))) files[path] = readFileSync(join(dir, path), "utf8");
96
+ const skillsDir = join(dir, "skills");
97
+ if (existsSync(skillsDir))
98
+ for (const entry of readdirSync(skillsDir, { withFileTypes: true }))
99
+ if (entry.isDirectory() && existsSync(join(skillsDir, entry.name, "SKILL.md")))
100
+ files[`skills/${entry.name}/SKILL.md`] = readFileSync(
101
+ join(skillsDir, entry.name, "SKILL.md"),
102
+ "utf8",
103
+ );
104
+ return parsePlugin(files);
105
+ }
package/src/service.ts CHANGED
@@ -7,6 +7,7 @@ import {
7
7
 
8
8
  import { createVerifier, type Caller, type ZitadelAuthOptions } from "./bearer";
9
9
  import { callLine, type CallLine } from "./log";
10
+ import type { AgentPlugin } from "./plugin";
10
11
  import { isRefusal, refusalResult, toResult, type ToolDefinition } from "./tool";
11
12
 
12
13
  export interface McpServiceOptions {
@@ -25,6 +26,8 @@ export interface McpServiceOptions {
25
26
  // Инструменты разных схем: тип аргументов проверен в defineTool.
26
27
  // oxlint-disable-next-line no-explicit-any
27
28
  tools: ToolDefinition<any>[];
29
+ /** Плагин агента модуля: отдаётся на `<basePath>/agent/plugin.json` тем, у кого все его роли. */
30
+ plugin?: AgentPlugin;
28
31
  /** Журнал вызовов инструментов; по умолчанию — строка JSON в stdout. */
29
32
  log?: (line: CallLine) => void;
30
33
  }
@@ -65,6 +68,7 @@ export function mcpPaths(o: Pick<McpServiceOptions, "basePath" | "mcpPath">) {
65
68
  mcp,
66
69
  health: `${base}/health`,
67
70
  card: `${base}/.well-known/mcp/server-card.json`,
71
+ plugin: `${base}/agent/plugin.json`,
68
72
  metadata,
69
73
  metadataPaths: [...new Set([metadata, `${base}${metadata}`])],
70
74
  };
@@ -176,7 +180,11 @@ export function createMcpService(options: McpServiceOptions) {
176
180
  },
177
181
  );
178
182
 
179
- async function serveMcp(request: Request): Promise<Response> {
183
+ /** Токен и роли: вызывающий или готовый отказ — одна проверка для MCP и плагина. */
184
+ async function authenticate(
185
+ request: Request,
186
+ roles: (string | undefined)[],
187
+ ): Promise<{ token: string; caller: Caller } | Response> {
180
188
  const header = request.headers.get("authorization") ?? "";
181
189
  const token = /^Bearer\s+/i.test(header) ? header.replace(/^Bearer\s+/i, "").trim() : "";
182
190
  if (!token) return challenge(401, null, "нужен токен: Authorization: Bearer <token>");
@@ -188,9 +196,15 @@ export function createMcpService(options: McpServiceOptions) {
188
196
  "invalid_token",
189
197
  "токен не принят: подпись, издатель, аудитория или срок",
190
198
  );
191
- const role = options.auth.role;
192
- if (role && !caller.roles.includes(role))
193
- return challenge(403, "insufficient_scope", `нет роли проекта ${role}`);
199
+ const missing = roles.find((r) => r && !caller.roles.includes(r));
200
+ if (missing) return challenge(403, "insufficient_scope", `нет роли проекта ${missing}`);
201
+ return { token, caller };
202
+ }
203
+
204
+ async function serveMcp(request: Request): Promise<Response> {
205
+ const auth = await authenticate(request, [options.auth.role]);
206
+ if (auth instanceof Response) return auth;
207
+ const { token, caller } = auth;
194
208
  const authInfo: AuthInfo = {
195
209
  token,
196
210
  clientId: caller.clientId,
@@ -207,6 +221,16 @@ export function createMcpService(options: McpServiceOptions) {
207
221
  return new Response(response.body, { status: response.status, headers });
208
222
  }
209
223
 
224
+ // Плагин — указания агента: только служебной учётке с ролями из манифеста, как инструменты.
225
+ // Адрес MCP — свой, из настроек сервиса: .mcp.json репозитория мог указывать на другое окружение.
226
+ async function servePlugin(request: Request, plugin: AgentPlugin): Promise<Response> {
227
+ const auth = await authenticate(request, [options.auth.role, ...plugin.roles]);
228
+ if (auth instanceof Response) return auth;
229
+ return json({ ...plugin, mcp: { url: `${origin}${paths.mcp}` } }, 200, {
230
+ "cache-control": "no-store",
231
+ });
232
+ }
233
+
210
234
  const publicDoc = (body: unknown) => json(body, 200, { "cache-control": "public, max-age=300" });
211
235
 
212
236
  async function fetch(request: Request): Promise<Response> {
@@ -218,13 +242,23 @@ export function createMcpService(options: McpServiceOptions) {
218
242
  if (path === paths.health)
219
243
  return json({ ok: true, name: options.name, version: options.version });
220
244
  if (path === paths.card) return publicDoc(card);
245
+ if (options.plugin && path === paths.plugin) return servePlugin(request, options.plugin);
221
246
  if (paths.metadataPaths.includes(path)) return publicDoc(metadata);
222
247
  return json({ error: "not_found" }, 404);
223
248
  }
224
249
 
225
250
  return {
226
251
  fetch,
227
- paths: { ...paths, all: [paths.mcp, paths.health, paths.card, ...paths.metadataPaths] },
252
+ paths: {
253
+ ...paths,
254
+ all: [
255
+ paths.mcp,
256
+ paths.health,
257
+ paths.card,
258
+ ...paths.metadataPaths,
259
+ ...(options.plugin ? [paths.plugin] : []),
260
+ ],
261
+ },
228
262
  card,
229
263
  close: () => mcp.close(),
230
264
  };