@dxos/introspect-mcp 0.0.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.
Files changed (50) hide show
  1. package/README.md +212 -0
  2. package/bin/dx-introspect-mcp.mjs +11 -0
  3. package/dist/lib/node-esm/chunk-63HTIHM3.mjs +400 -0
  4. package/dist/lib/node-esm/chunk-63HTIHM3.mjs.map +7 -0
  5. package/dist/lib/node-esm/index.mjs +270 -0
  6. package/dist/lib/node-esm/index.mjs.map +7 -0
  7. package/dist/lib/node-esm/meta.json +1 -0
  8. package/dist/lib/node-esm/tools/index.mjs +34 -0
  9. package/dist/lib/node-esm/tools/index.mjs.map +7 -0
  10. package/dist/types/src/cli.d.ts +2 -0
  11. package/dist/types/src/cli.d.ts.map +1 -0
  12. package/dist/types/src/index.d.ts +3 -0
  13. package/dist/types/src/index.d.ts.map +1 -0
  14. package/dist/types/src/server/http.test.d.ts +2 -0
  15. package/dist/types/src/server/http.test.d.ts.map +1 -0
  16. package/dist/types/src/server/index.d.ts +3 -0
  17. package/dist/types/src/server/index.d.ts.map +1 -0
  18. package/dist/types/src/server/main.d.ts +2 -0
  19. package/dist/types/src/server/main.d.ts.map +1 -0
  20. package/dist/types/src/server/server.d.ts +14 -0
  21. package/dist/types/src/server/server.d.ts.map +1 -0
  22. package/dist/types/src/server/server.test.d.ts +2 -0
  23. package/dist/types/src/server/server.test.d.ts.map +1 -0
  24. package/dist/types/src/server/stdio.test.d.ts +2 -0
  25. package/dist/types/src/server/stdio.test.d.ts.map +1 -0
  26. package/dist/types/src/tools/index.d.ts +4 -0
  27. package/dist/types/src/tools/index.d.ts.map +1 -0
  28. package/dist/types/src/tools/logger.d.ts +20 -0
  29. package/dist/types/src/tools/logger.d.ts.map +1 -0
  30. package/dist/types/src/tools/shaping.d.ts +24 -0
  31. package/dist/types/src/tools/shaping.d.ts.map +1 -0
  32. package/dist/types/src/tools/tools.d.ts +38 -0
  33. package/dist/types/src/tools/tools.d.ts.map +1 -0
  34. package/dist/types/src/tools/tools.test.d.ts +2 -0
  35. package/dist/types/src/tools/tools.test.d.ts.map +1 -0
  36. package/dist/types/tsconfig.tsbuildinfo +1 -0
  37. package/package.json +53 -0
  38. package/src/cli.ts +13 -0
  39. package/src/index.ts +10 -0
  40. package/src/server/http.test.ts +89 -0
  41. package/src/server/index.ts +10 -0
  42. package/src/server/main.ts +275 -0
  43. package/src/server/server.test.ts +215 -0
  44. package/src/server/server.ts +79 -0
  45. package/src/server/stdio.test.ts +76 -0
  46. package/src/tools/index.ts +28 -0
  47. package/src/tools/logger.ts +60 -0
  48. package/src/tools/shaping.ts +194 -0
  49. package/src/tools/tools.test.ts +78 -0
  50. package/src/tools/tools.ts +212 -0
package/README.md ADDED
@@ -0,0 +1,212 @@
1
+ # @dxos/introspect-mcp
2
+
3
+ MCP server that exposes [@dxos/introspect](../introspect) over stdio.
4
+ Lets LLM tools (Claude Code, etc.) query the DXOS monorepo's package, symbol, and plugin graph.
5
+
6
+ Coverage so far:
7
+ - **Phase 1** — packages and symbols.
8
+ - **Phase 2** — plugins, surfaces, capabilities, operations (extracted statically from `Plugin.define` / `Surface.create` / `Capability.contributes` / `Operation.make`).
9
+ - **Phase 3** — ECHO-registered schemas (`Type.object` / `Type.Obj`).
10
+
11
+ Idioms, composition queries, and UI components are next (see [SPEC.md](../introspect/SPEC.md#build-order)).
12
+
13
+ ## Tools
14
+
15
+ ### Packages & symbols
16
+
17
+ | Tool | Purpose |
18
+ | --- | --- |
19
+ | `list_packages` | List packages, with optional `name` / `pathPrefix` / `privateOnly` filters. |
20
+ | `get_package` | Full record for one package: workspace + external deps, entry points. |
21
+ | `list_symbols` | Enumerate every exported symbol of a single package, optionally filtered by kind. |
22
+ | `find_symbol` | Locate an exported symbol by name (case-insensitive); ranks exact > prefix > substring. |
23
+ | `get_symbol` | Detail for one symbol by ref. Pass `include=["source"]` to expand the body. |
24
+
25
+ ### Plugin ecosystem
26
+
27
+ | Tool | Purpose |
28
+ | --- | --- |
29
+ | `list_plugins` | List detected plugins (any package with a `Plugin.define(meta)` call + `meta.ts`). |
30
+ | `get_plugin` | Full record for one plugin by id: meta, modules wired via `.pipe(...)`, and the surfaces / capabilities / operations it contributes. |
31
+ | `list_surfaces` | Aggregate every `Surface.create({ id, role, ... })` contribution. Filter by `pluginId`. |
32
+ | `list_capabilities` | Aggregate every `Capability.contributes(<key>, ...)` call. Filter by `pluginId`. |
33
+ | `list_operations` | Aggregate every `Operation.make({ meta: { key, name, description } })` definition. Filter by `pluginId`. |
34
+
35
+ ### Schemas (ECHO-registered types)
36
+
37
+ | Tool | Purpose |
38
+ | --- | --- |
39
+ | `list_schemas` | List every ECHO-registered type — `Schema.Struct(...).pipe(Type.object({ typename, version }))` and the lowercase `Type.Obj(...)` variant used inside `@dxos/echo` internals. Filter by `pluginId` (most common — narrows to a single plugin's schemas) or `package`. |
40
+ | `get_schema` | Detail for one schema by typename: full field list, version, owning package, source location. |
41
+ | `find_schema_usage` | Every line in the monorepo that mentions a typename — references, JSDoc, plugin wiring. The defining `Type.object` line is excluded. |
42
+
43
+ Tool descriptions are written for LLM trigger accuracy — they describe *when* to use a tool, not just what it does.
44
+
45
+ ## Try it (browser UI)
46
+
47
+ Quickest hands-on path — launches the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector) against this server, with all paths pre-baked:
48
+
49
+ ```bash
50
+ moon run introspect-mcp:inspect
51
+ ```
52
+
53
+ The terminal prints a URL containing `?MCP_PROXY_AUTH_TOKEN=...`. Open *that exact URL* in your browser, click **Connect** → **Tools** → **List Tools** → pick a tool → **Run Tool**.
54
+
55
+ See [Test it from a browser (MCP Inspector)](#test-it-from-a-browser-mcp-inspector) below for troubleshooting.
56
+
57
+ ## Running it
58
+
59
+ You normally don't run this server directly — let Claude Code or the MCP Inspector spawn it for you (see sections below). For the rare case of a custom client or manual probing:
60
+
61
+ ```bash
62
+ moon run introspect-mcp:serve
63
+ ```
64
+
65
+ The server speaks JSON-RPC over stdio: it reads requests from stdin and writes responses to stdout, blocking until stdin closes. Configure your MCP client to spawn `npx tsx --conditions=source packages/core/introspect-mcp/src/cli.ts` from the repo root — this is exactly what `.mcp.json` does.
66
+
67
+ CLI flags:
68
+ - `--root <path>` — monorepo root (defaults to the nearest ancestor of cwd containing `pnpm-workspace.yaml`).
69
+ - `--log-path <path>` — append-only JSONL log of every tool call.
70
+
71
+ ## Response shaping
72
+
73
+ - List responses cap at 30 items and include a `truncated` note when more exist.
74
+ - `get_symbol` returns signature + summary + location by default; full source/JSDoc require explicit `include`.
75
+ - Long source/JSDoc bodies are truncated with a marker — call again with a narrower question if needed.
76
+
77
+ ## Use it from Claude Code
78
+
79
+ The repo ships a project-scoped [`.mcp.json`](../../../.mcp.json) at the repo root that registers `dxos-introspect`. **Claude Code spawns the server automatically** as a stdio subprocess on launch — you don't start it manually.
80
+
81
+ 1. **Verify the config works** — runs the same spawn Claude Code will use, completes a real JSON-RPC `initialize` + `tools/list` + `tools/call list_packages`, and exits 0 on success:
82
+
83
+ ```bash
84
+ moon run introspect-mcp:check
85
+ ```
86
+
87
+ 2. **Restart Claude Code** (Cmd+Q + relaunch). Type `/mcp` to confirm `dxos-introspect ✓ connected`.
88
+
89
+ 3. Try it: ask Claude *"list every symbol in @dxos/echo-react"*.
90
+
91
+ ## Use it from Composer (plugin-assistant)
92
+
93
+ Composer's `plugin-assistant` accepts MCP servers by URL (HTTP / SSE only — not stdio). To bridge, run the server in HTTP mode:
94
+
95
+ ```bash
96
+ moon run introspect-mcp:serve-http
97
+ ```
98
+
99
+ This binds to `http://localhost:39476/mcp` (Streamable HTTP transport, stateful sessions).
100
+
101
+ Then in Composer:
102
+
103
+ 1. Open a chat → click the **chat options** icon → **MCP servers** tab → **Add MCP server**.
104
+ 2. Fill in:
105
+ - **Name**: `dxos-introspect`
106
+ - **Server URL**: `http://localhost:39476/mcp`
107
+ - **Protocol**: `http`
108
+ - **API key**: leave empty (no auth — see below)
109
+ 3. Save and toggle **enabled**. Every tool listed in the [Tools](#tools) section above becomes available to the assistant — packages and symbols, plugin ecosystem (plugins / surfaces / capabilities / operations), and ECHO-registered schemas.
110
+
111
+ **Auth:** by default the HTTP server accepts unauthenticated requests on localhost only. To require a bearer token (e.g. when running from a remote machine), pass `--api-key <token>` to `cli.ts` and put the same token in Composer's MCP server **API key** field.
112
+
113
+ ```bash
114
+ pnpm exec tsx --conditions=source packages/core/introspect-mcp/src/cli.ts \
115
+ --http 39476 --api-key sekret
116
+ ```
117
+
118
+ ## Test it from a browser (MCP Inspector)
119
+
120
+ Launches the official MCP Inspector UI against this server, with all paths pre-baked:
121
+
122
+ ```bash
123
+ moon run introspect-mcp:inspect
124
+ ```
125
+
126
+ The terminal prints a URL containing `?MCP_PROXY_AUTH_TOKEN=...`. **Open that exact URL** in your browser (the token is required; clicking through to plain `http://localhost:6274` will fail). The Inspector spawns the same `cli.ts` that Claude Code does.
127
+
128
+ In the UI: Transport must be `STDIO` (the form is pre-filled). Click **Connect** → **Tools** → **List Tools** → pick a tool → **Run Tool**.
129
+
130
+ ### If "Connect" doesn't work
131
+
132
+ Most often a stale Inspector process is holding ports `6274` / `6277`, or your browser tab is pointed at an Inspector instance that's been killed (so the auth token is invalid).
133
+
134
+ Reset cleanly:
135
+
136
+ ```bash
137
+ lsof -ti:6274,6277 | xargs kill -9
138
+ ```
139
+ ```bash
140
+ pkill -f "tsx.*introspect-mcp"
141
+ ```
142
+ ```bash
143
+ moon run introspect-mcp:check
144
+ ```
145
+ ```bash
146
+ moon run introspect-mcp:inspect
147
+ ```
148
+
149
+ Open *only* the URL the new Inspector prints (with the auth token). Click Connect.
150
+
151
+ If `moon run introspect-mcp:check` fails, run `moon run introspect-mcp:sanity` for additional named-checkpoint diagnostics.
152
+
153
+ ## Run the server standalone
154
+
155
+ For piping JSON-RPC by hand or wiring into a different MCP client:
156
+
157
+ ```bash
158
+ moon run introspect-mcp:serve
159
+ ```
160
+
161
+ Runs the server attached to your terminal stdio, blocking for input. Send JSON-RPC requests to its stdin; responses come on stdout. Useful only if you're testing with a custom client; for the normal case, let Claude Code or the Inspector spawn it.
162
+
163
+ ## Other testing entry points
164
+
165
+ | Command | What it does |
166
+ | --- | --- |
167
+ | `moon run introspect-mcp:test` | Unit + integration tests (in-memory and real-stdio subprocess), ~3s |
168
+ | `moon run introspect-mcp:check` | End-to-end: spawns the server with the exact command from `.mcp.json` and round-trips a tool call. **Run before restarting Claude Code.** |
169
+ | `moon run introspect-mcp:inspect` | Launch the MCP Inspector (browser UI) against this server, with all paths absolutized. Cold cache may take ~80s; subsequent runs <1s. |
170
+ | `moon run introspect-mcp:sanity` | Inspector + proxy auth check — confirms the launcher succeeds and the proxy responds with a valid auth token. |
171
+ | `moon run introspect-mcp:serve` | Raw stdio server, for piping requests in by hand. |
172
+ | `moon run introspect-mcp:serve-http` | HTTP server on `localhost:39476/mcp`. Use this to wire the server into Composer's plugin-assistant or any other HTTP/SSE-only MCP client. |
173
+ | `moon run introspect:index` | Pre-build the on-disk symbol cache (`<root>/node_modules/.cache/dxos-introspect/`). The cache makes server startup near-instant. |
174
+ | `moon run introspect-mcp:fetch-cache` | Download the prebuilt cache from the latest CI run on main and install it locally. Skips the ~80s cold-start parse for ~95% of packages on a clean main checkout. Requires `gh` CLI authenticated (`gh auth login`). |
175
+
176
+ ## Why `--conditions=source`?
177
+
178
+ The package.json `exports` field has a `source` condition pointing at `src/index.ts`. Without `--conditions=source`, `tsx` falls through to the `default` condition (`dist/lib/node/index.mjs`) which doesn't exist unless you've run a build. The flag lets the server boot from source with no build step — same behavior the rest of the DXOS toolchain relies on.
179
+
180
+ ## Cache
181
+
182
+ The indexer stores extracted symbols at `<repo-root>/node_modules/.cache/dxos-introspect/cache.json` (~13 MB for 250 packages). Following the babel/swc/eslint convention so it's auto-gitignored and gets nuked by `pnpm clean`. Saves are atomic (write-temp-then-rename), so concurrent introspector processes can't corrupt each other.
183
+
184
+ ### Invalidation
185
+
186
+ Each entry records:
187
+
188
+ - the **git tree SHA** of `<package>/src` at HEAD when the entry was written, and
189
+ - the most-recent **mtime** under `<package>/src`.
190
+
191
+ On load, an entry is reused if the live tree SHA matches the cached one (portable across machines — same git ref → same SHA), and falls back to mtime equality otherwise (covers uncommitted local edits before they're committed). Anything that doesn't match is dropped and re-extracted on demand.
192
+
193
+ A package with uncommitted changes under its `src/` is treated as not-in-git for tree-SHA purposes — its srcTreeSha is empty in both the live probe and any saved entry, so it always falls through to the mtime path. This means dirty work-in-progress edits never falsely match a CI-built cache.
194
+
195
+ ### Prebuilt cache from CI
196
+
197
+ The [`Introspect Cache`](../../../.github/workflows/introspect-cache.yml) workflow runs on every commit to main and uploads the cache as a GitHub Actions artifact. To install it locally instead of building from scratch:
198
+
199
+ ```bash
200
+ moon run introspect-mcp:fetch-cache
201
+ ```
202
+
203
+ This calls `gh run download` against the most recent successful workflow run on main and drops the cache at the canonical path. Per-package validity is decided by tree SHA, so any package whose `src/` is unchanged from that commit is reused; the rest re-extract on demand. On a clean main checkout you typically get >95% reuse; first MCP server start drops from ~80s to a few seconds.
204
+
205
+ ### Force a fresh build
206
+
207
+ ```bash
208
+ rm -rf node_modules/.cache/dxos-introspect
209
+ moon run introspect:index
210
+ ```
211
+
212
+ Otherwise the cache auto-invalidates per package whenever `src/` changes (tree SHA on commit, mtime in between).
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env node
2
+ //
3
+ // Copyright 2026 DXOS.org
4
+ //
5
+
6
+ import { main } from '../dist/lib/node/main.mjs';
7
+
8
+ main().catch((err) => {
9
+ console.error(err);
10
+ process.exit(1);
11
+ });
@@ -0,0 +1,400 @@
1
+ import { createRequire } from 'node:module';const require = createRequire(import.meta.url);
2
+
3
+ // src/tools/tools.ts
4
+ import { TOOL_METADATA } from "@dxos/introspect-tools";
5
+
6
+ // src/tools/shaping.ts
7
+ import { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from "@dxos/introspect-tools";
8
+ var SOURCE_PREVIEW = 1200;
9
+ var JSDOC_PREVIEW = 600;
10
+ var shapeList = (all, opts, config) => {
11
+ const requested = opts.limit ?? DEFAULT_LIST_LIMIT;
12
+ const limit = Math.min(Math.max(0, Math.floor(requested)), MAX_LIST_LIMIT);
13
+ const project = opts.compact ? config.compact : config.full;
14
+ const data = all.slice(0, limit).map(project);
15
+ if (all.length > limit) {
16
+ return {
17
+ data,
18
+ truncated: `${all.length - limit} more results \u2014 ${config.truncationHint}`
19
+ };
20
+ }
21
+ return {
22
+ data
23
+ };
24
+ };
25
+ var shapeListPackages = (all, opts = {}) => shapeList(all, opts, {
26
+ full: (p) => ({
27
+ name: p.name,
28
+ version: p.version,
29
+ private: p.private,
30
+ path: p.path,
31
+ description: p.description
32
+ }),
33
+ compact: (p) => ({
34
+ name: p.name,
35
+ path: p.path
36
+ }),
37
+ truncationHint: "raise `limit` (max 200), refine with `name`/`pathPrefix`, or call get_package directly."
38
+ });
39
+ var shapeGetPackage = (detail) => ({
40
+ data: {
41
+ name: detail.name,
42
+ version: detail.version,
43
+ private: detail.private,
44
+ path: detail.path,
45
+ description: detail.description,
46
+ workspaceDependencies: detail.workspaceDependencies,
47
+ externalDependencies: detail.externalDependencies,
48
+ entryPoints: detail.entryPoints,
49
+ // Surfaced so callers can decide whether to call find_symbol against this package.
50
+ exportCount: detail.exportCount
51
+ }
52
+ });
53
+ var shapeFindSymbol = (matches, opts = {}) => shapeList(matches, opts, {
54
+ full: (m) => ({
55
+ ref: m.ref,
56
+ name: m.name,
57
+ package: m.package,
58
+ kind: m.kind,
59
+ summary: m.summary
60
+ }),
61
+ compact: (m) => ({
62
+ ref: m.ref,
63
+ name: m.name
64
+ }),
65
+ truncationHint: "raise `limit` (max 200), refine the query, or filter by `kind`."
66
+ });
67
+ var shapeGetSymbol = (detail) => {
68
+ const result = {
69
+ ref: detail.ref,
70
+ package: detail.package,
71
+ name: detail.name,
72
+ kind: detail.kind,
73
+ signature: detail.signature,
74
+ summary: detail.summary,
75
+ location: detail.location
76
+ };
77
+ if (detail.jsdoc) {
78
+ result.jsdoc = truncate(detail.jsdoc, JSDOC_PREVIEW);
79
+ }
80
+ if (detail.source !== void 0) {
81
+ result.source = truncate(detail.source, SOURCE_PREVIEW);
82
+ }
83
+ return {
84
+ data: result
85
+ };
86
+ };
87
+ var truncate = (s, limit) => {
88
+ if (s.length <= limit) {
89
+ return s;
90
+ }
91
+ return `${s.slice(0, limit)}
92
+ ... (truncated, ${s.length - limit} more chars)`;
93
+ };
94
+ var shapeListPlugins = (all, opts = {}) => shapeList(all, opts, {
95
+ full: (p) => ({
96
+ id: p.id,
97
+ package: p.package,
98
+ name: p.name,
99
+ description: p.description,
100
+ icon: p.icon,
101
+ iconHue: p.iconHue
102
+ }),
103
+ compact: (p) => ({
104
+ id: p.id,
105
+ name: p.name
106
+ }),
107
+ truncationHint: "raise `limit` (max 200) or filter with `id` substring."
108
+ });
109
+ var shapePluginDetail = (detail) => ({
110
+ data: {
111
+ id: detail.id,
112
+ package: detail.package,
113
+ name: detail.name,
114
+ description: detail.description,
115
+ icon: detail.icon,
116
+ iconHue: detail.iconHue,
117
+ metaLocation: detail.metaLocation,
118
+ surfaces: detail.surfaces.map((s) => ({
119
+ id: s.id,
120
+ role: s.role
121
+ })),
122
+ capabilities: detail.capabilities.map((c) => ({
123
+ type: c.type
124
+ })),
125
+ operations: detail.operations.map((o) => ({
126
+ type: o.type
127
+ })),
128
+ schemas: detail.schemas.map((s) => ({
129
+ name: s.name,
130
+ typename: s.typename
131
+ }))
132
+ }
133
+ });
134
+ var shapeListSurfaces = (all, opts = {}) => shapeList(all, opts, {
135
+ full: (s) => ({
136
+ pluginId: s.pluginId,
137
+ id: s.id,
138
+ role: s.role,
139
+ location: s.location
140
+ }),
141
+ compact: (s) => ({
142
+ pluginId: s.pluginId,
143
+ id: s.id
144
+ }),
145
+ truncationHint: "raise `limit` (max 200) or filter by plugin `id`."
146
+ });
147
+ var shapeListCapabilities = (all, opts = {}) => shapeList(all, opts, {
148
+ full: (c) => ({
149
+ pluginId: c.pluginId,
150
+ type: c.type,
151
+ location: c.location
152
+ }),
153
+ compact: (c) => ({
154
+ pluginId: c.pluginId,
155
+ type: c.type
156
+ }),
157
+ truncationHint: "raise `limit` (max 200) or filter by plugin `id`."
158
+ });
159
+ var shapeListOperations = (all, opts = {}) => shapeList(all, opts, {
160
+ full: (o) => ({
161
+ pluginId: o.pluginId,
162
+ type: o.type,
163
+ location: o.location
164
+ }),
165
+ compact: (o) => ({
166
+ pluginId: o.pluginId,
167
+ type: o.type
168
+ }),
169
+ truncationHint: "raise `limit` (max 200) or filter by plugin `id`."
170
+ });
171
+ var shapeListSchemas = (all, opts = {}) => shapeList(all, opts, {
172
+ full: (s) => ({
173
+ pluginId: s.pluginId,
174
+ name: s.name,
175
+ typename: s.typename,
176
+ location: s.location
177
+ }),
178
+ compact: (s) => ({
179
+ pluginId: s.pluginId,
180
+ name: s.name,
181
+ typename: s.typename
182
+ }),
183
+ truncationHint: "raise `limit` (max 200) or filter by plugin `id`."
184
+ });
185
+
186
+ // src/tools/tools.ts
187
+ var pickListOptions = (args) => ({
188
+ limit: args.limit,
189
+ compact: args.compact
190
+ });
191
+ var createToolDefinitions = (introspector, log) => ({
192
+ list_packages: {
193
+ ...TOOL_METADATA.list_packages,
194
+ handler: (args) => {
195
+ const result = introspector.listPackages({
196
+ name: args.name,
197
+ pathPrefix: args.pathPrefix,
198
+ privateOnly: args.privateOnly
199
+ });
200
+ const shaped = shapeListPackages(result, pickListOptions(args));
201
+ log({
202
+ tool: "list_packages",
203
+ args,
204
+ count: result.length,
205
+ truncated: shaped.truncated
206
+ });
207
+ return shaped;
208
+ }
209
+ },
210
+ get_package: {
211
+ ...TOOL_METADATA.get_package,
212
+ handler: (args) => {
213
+ const detail = introspector.getPackage(args.name);
214
+ log({
215
+ tool: "get_package",
216
+ args,
217
+ found: detail !== null
218
+ });
219
+ if (!detail) {
220
+ return {
221
+ data: null,
222
+ note: `No package named ${args.name}`
223
+ };
224
+ }
225
+ return shapeGetPackage(detail);
226
+ }
227
+ },
228
+ list_symbols: {
229
+ ...TOOL_METADATA.list_symbols,
230
+ handler: (args) => {
231
+ const matches = introspector.listSymbols(args.package, args.kind);
232
+ const shaped = shapeFindSymbol(matches, pickListOptions(args));
233
+ log({
234
+ tool: "list_symbols",
235
+ args,
236
+ count: matches.length,
237
+ truncated: shaped.truncated
238
+ });
239
+ return shaped;
240
+ }
241
+ },
242
+ find_symbol: {
243
+ ...TOOL_METADATA.find_symbol,
244
+ handler: (args) => {
245
+ const matches = introspector.findSymbol(args.query, args.kind);
246
+ const shaped = shapeFindSymbol(matches, pickListOptions(args));
247
+ log({
248
+ tool: "find_symbol",
249
+ args,
250
+ count: matches.length,
251
+ truncated: shaped.truncated
252
+ });
253
+ return shaped;
254
+ }
255
+ },
256
+ get_symbol: {
257
+ ...TOOL_METADATA.get_symbol,
258
+ handler: (args) => {
259
+ const detail = introspector.getSymbol(args.ref, args.include);
260
+ log({
261
+ tool: "get_symbol",
262
+ args,
263
+ found: detail !== null
264
+ });
265
+ if (!detail) {
266
+ return {
267
+ data: null,
268
+ note: `No symbol with ref ${args.ref}`
269
+ };
270
+ }
271
+ return shapeGetSymbol(detail);
272
+ }
273
+ },
274
+ list_plugins: {
275
+ ...TOOL_METADATA.list_plugins,
276
+ handler: (args) => {
277
+ const result = introspector.listPlugins(args.id !== void 0 ? {
278
+ id: args.id
279
+ } : void 0);
280
+ const shaped = shapeListPlugins(result, pickListOptions(args));
281
+ log({
282
+ tool: "list_plugins",
283
+ args,
284
+ count: result.length,
285
+ truncated: shaped.truncated
286
+ });
287
+ return shaped;
288
+ }
289
+ },
290
+ list_surfaces: {
291
+ ...TOOL_METADATA.list_surfaces,
292
+ handler: (args) => {
293
+ const result = introspector.listSurfaces(args.id);
294
+ const shaped = shapeListSurfaces(result, pickListOptions(args));
295
+ log({
296
+ tool: "list_surfaces",
297
+ args,
298
+ count: result.length,
299
+ truncated: shaped.truncated
300
+ });
301
+ return shaped;
302
+ }
303
+ },
304
+ list_capabilities: {
305
+ ...TOOL_METADATA.list_capabilities,
306
+ handler: (args) => {
307
+ const result = introspector.listCapabilities(args.id);
308
+ const shaped = shapeListCapabilities(result, pickListOptions(args));
309
+ log({
310
+ tool: "list_capabilities",
311
+ args,
312
+ count: result.length,
313
+ truncated: shaped.truncated
314
+ });
315
+ return shaped;
316
+ }
317
+ },
318
+ list_operations: {
319
+ ...TOOL_METADATA.list_operations,
320
+ handler: (args) => {
321
+ const result = introspector.listOperations(args.id);
322
+ const shaped = shapeListOperations(result, pickListOptions(args));
323
+ log({
324
+ tool: "list_operations",
325
+ args,
326
+ count: result.length,
327
+ truncated: shaped.truncated
328
+ });
329
+ return shaped;
330
+ }
331
+ },
332
+ list_schemas: {
333
+ ...TOOL_METADATA.list_schemas,
334
+ handler: (args) => {
335
+ const result = introspector.listSchemas(args.id);
336
+ const shaped = shapeListSchemas(result, pickListOptions(args));
337
+ log({
338
+ tool: "list_schemas",
339
+ args,
340
+ count: result.length,
341
+ truncated: shaped.truncated
342
+ });
343
+ return shaped;
344
+ }
345
+ }
346
+ });
347
+
348
+ // src/tools/logger.ts
349
+ import { appendFile, mkdir } from "node:fs/promises";
350
+ import { dirname } from "node:path";
351
+ var noopLogger = () => {
352
+ };
353
+ var registerLogger = (inner) => {
354
+ if (!inner) {
355
+ return noopLogger;
356
+ }
357
+ return (entry) => {
358
+ try {
359
+ inner(entry);
360
+ } catch {
361
+ }
362
+ };
363
+ };
364
+ var fileLogger = (path) => {
365
+ let ensured = false;
366
+ return (entry) => {
367
+ const line = `${JSON.stringify({
368
+ ts: (/* @__PURE__ */ new Date()).toISOString(),
369
+ ...entry
370
+ })}
371
+ `;
372
+ void (async () => {
373
+ if (!ensured) {
374
+ await mkdir(dirname(path), {
375
+ recursive: true
376
+ });
377
+ ensured = true;
378
+ }
379
+ await appendFile(path, line, "utf8");
380
+ })().catch(() => void 0);
381
+ };
382
+ };
383
+
384
+ export {
385
+ shapeListPackages,
386
+ shapeGetPackage,
387
+ shapeFindSymbol,
388
+ shapeGetSymbol,
389
+ shapeListPlugins,
390
+ shapePluginDetail,
391
+ shapeListSurfaces,
392
+ shapeListCapabilities,
393
+ shapeListOperations,
394
+ shapeListSchemas,
395
+ createToolDefinitions,
396
+ noopLogger,
397
+ registerLogger,
398
+ fileLogger
399
+ };
400
+ //# sourceMappingURL=chunk-63HTIHM3.mjs.map