@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
@@ -0,0 +1,212 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ // Tool definitions — the metadata + handler body for every MCP tool the
6
+ // introspect-mcp server exposes.
7
+ //
8
+ // Centralizing this map gives us:
9
+ //
10
+ // - One place to read when wondering "what tools does this server expose?"
11
+ // - A simple shape for `server.ts` to iterate when registering tools, so the
12
+ // server's only job is wiring (transport, error handling, readiness gate).
13
+ // - A natural surface to extend without touching server-construction logic
14
+ // — adding a tool is a single new entry in this map.
15
+ //
16
+ // Input schemas are authored in Effect Schema (see `@dxos/introspect-tools`)
17
+ // so that downstream consumers like `react-ui-form` can render forms from
18
+ // the same definitions. The MCP SDK requires zod, so the server converts at
19
+ // registration time via `inputSchemaToZod` from `@dxos/introspect-tools`.
20
+ //
21
+ // Each handler returns a `ToolResult` (data + optional note + optional
22
+ // truncated marker); the server wraps that in the MCP `content` envelope.
23
+ // Handlers DO NOT call `await introspector.ready` themselves — the server
24
+ // applies that gate uniformly via `withReady`, so a future tool can't
25
+ // accidentally skip it.
26
+
27
+ import type * as Schema from 'effect/Schema';
28
+
29
+ import type { Introspector } from '@dxos/introspect';
30
+ import {
31
+ TOOL_METADATA,
32
+ type FindSymbolArgs,
33
+ type GetPackageArgs,
34
+ type GetSymbolArgs,
35
+ type ListCapabilitiesArgs,
36
+ type ListOperationsArgs,
37
+ type ListOptions,
38
+ type ListPackagesArgs,
39
+ type ListPluginsArgs,
40
+ type ListSchemasArgs,
41
+ type ListSurfacesArgs,
42
+ type ListSymbolsArgs,
43
+ } from '@dxos/introspect-tools';
44
+
45
+ import type { ToolLogger } from './logger';
46
+ import {
47
+ shapeFindSymbol,
48
+ shapeGetPackage,
49
+ shapeGetSymbol,
50
+ shapeListCapabilities,
51
+ shapeListOperations,
52
+ shapeListPackages,
53
+ shapeListPlugins,
54
+ shapeListSchemas,
55
+ shapeListSurfaces,
56
+ type ToolResult,
57
+ } from './shaping';
58
+
59
+ /** Pull the list-options bag out of an args object before forwarding to a shaper. */
60
+ const pickListOptions = (args: { limit?: number; compact?: boolean }): ListOptions => ({
61
+ limit: args.limit,
62
+ compact: args.compact,
63
+ });
64
+
65
+ /**
66
+ * A single MCP tool — metadata + handler. The `inputSchema` field is the
67
+ * Effect `Schema.Struct` that defines the input shape; the server converts
68
+ * it to zod at registration via `effectFieldsToZod`. Authoring in Effect
69
+ * Schema gives `react-ui-form` and other downstream consumers a single
70
+ * source of truth.
71
+ */
72
+ export type ToolDefinition<TArgs = Record<string, unknown>> = {
73
+ /** Human-readable title surfaced by Inspector / Composer. */
74
+ title: string;
75
+
76
+ /**
77
+ * LLM-targeted description. Models read this to decide WHEN to call the
78
+ * tool — write it for trigger accuracy, not for human reading. State both
79
+ * what the tool does and the situations it's the right answer for.
80
+ */
81
+ description: string;
82
+
83
+ /**
84
+ * Effect Schema struct describing the tool's input. The server converts
85
+ * to zod for the MCP SDK; downstream consumers (react-ui-form, etc.) can
86
+ * use this directly.
87
+ */
88
+ inputSchema: Schema.Struct<any>;
89
+
90
+ /** Tool body. Must NOT await `introspector.ready` — the server gates that uniformly. */
91
+ handler: (args: TArgs) => ToolResult | Promise<ToolResult>;
92
+ };
93
+
94
+ /**
95
+ * Build the tool map for a given introspector. Returning a map (rather than a
96
+ * static const) lets the handlers close over the introspector instance and
97
+ * the per-process logger. Title / description / inputSchema all come from the
98
+ * shared `TOOL_METADATA` map in `@dxos/introspect-tools` so the contract is
99
+ * authored once and consumed by both server (here) and browser callers.
100
+ */
101
+ export const createToolDefinitions = (
102
+ introspector: Introspector,
103
+ log: ToolLogger,
104
+ ): Record<string, ToolDefinition<any>> => ({
105
+ list_packages: {
106
+ ...TOOL_METADATA.list_packages,
107
+ handler: (args: ListPackagesArgs) => {
108
+ const result = introspector.listPackages({
109
+ name: args.name,
110
+ pathPrefix: args.pathPrefix,
111
+ privateOnly: args.privateOnly,
112
+ });
113
+ const shaped = shapeListPackages(result, pickListOptions(args));
114
+ log({ tool: 'list_packages', args, count: result.length, truncated: shaped.truncated });
115
+ return shaped;
116
+ },
117
+ } satisfies ToolDefinition<ListPackagesArgs>,
118
+
119
+ get_package: {
120
+ ...TOOL_METADATA.get_package,
121
+ handler: (args: GetPackageArgs) => {
122
+ const detail = introspector.getPackage(args.name);
123
+ log({ tool: 'get_package', args, found: detail !== null });
124
+ if (!detail) {
125
+ return { data: null, note: `No package named ${args.name}` };
126
+ }
127
+ return shapeGetPackage(detail);
128
+ },
129
+ } satisfies ToolDefinition<GetPackageArgs>,
130
+
131
+ list_symbols: {
132
+ ...TOOL_METADATA.list_symbols,
133
+ handler: (args: ListSymbolsArgs) => {
134
+ const matches = introspector.listSymbols(args.package, args.kind);
135
+ const shaped = shapeFindSymbol(matches, pickListOptions(args));
136
+ log({ tool: 'list_symbols', args, count: matches.length, truncated: shaped.truncated });
137
+ return shaped;
138
+ },
139
+ } satisfies ToolDefinition<ListSymbolsArgs>,
140
+
141
+ find_symbol: {
142
+ ...TOOL_METADATA.find_symbol,
143
+ handler: (args: FindSymbolArgs) => {
144
+ const matches = introspector.findSymbol(args.query, args.kind);
145
+ const shaped = shapeFindSymbol(matches, pickListOptions(args));
146
+ log({ tool: 'find_symbol', args, count: matches.length, truncated: shaped.truncated });
147
+ return shaped;
148
+ },
149
+ } satisfies ToolDefinition<FindSymbolArgs>,
150
+
151
+ get_symbol: {
152
+ ...TOOL_METADATA.get_symbol,
153
+ handler: (args: GetSymbolArgs) => {
154
+ const detail = introspector.getSymbol(args.ref, args.include as Array<'source' | 'jsdoc'> | undefined);
155
+ log({ tool: 'get_symbol', args, found: detail !== null });
156
+ if (!detail) {
157
+ return { data: null, note: `No symbol with ref ${args.ref}` };
158
+ }
159
+ return shapeGetSymbol(detail);
160
+ },
161
+ } satisfies ToolDefinition<GetSymbolArgs>,
162
+
163
+ list_plugins: {
164
+ ...TOOL_METADATA.list_plugins,
165
+ handler: (args: ListPluginsArgs) => {
166
+ const result = introspector.listPlugins(args.id !== undefined ? { id: args.id } : undefined);
167
+ const shaped = shapeListPlugins(result, pickListOptions(args));
168
+ log({ tool: 'list_plugins', args, count: result.length, truncated: shaped.truncated });
169
+ return shaped;
170
+ },
171
+ } satisfies ToolDefinition<ListPluginsArgs>,
172
+
173
+ list_surfaces: {
174
+ ...TOOL_METADATA.list_surfaces,
175
+ handler: (args: ListSurfacesArgs) => {
176
+ const result = introspector.listSurfaces(args.id);
177
+ const shaped = shapeListSurfaces(result, pickListOptions(args));
178
+ log({ tool: 'list_surfaces', args, count: result.length, truncated: shaped.truncated });
179
+ return shaped;
180
+ },
181
+ } satisfies ToolDefinition<ListSurfacesArgs>,
182
+
183
+ list_capabilities: {
184
+ ...TOOL_METADATA.list_capabilities,
185
+ handler: (args: ListCapabilitiesArgs) => {
186
+ const result = introspector.listCapabilities(args.id);
187
+ const shaped = shapeListCapabilities(result, pickListOptions(args));
188
+ log({ tool: 'list_capabilities', args, count: result.length, truncated: shaped.truncated });
189
+ return shaped;
190
+ },
191
+ } satisfies ToolDefinition<ListCapabilitiesArgs>,
192
+
193
+ list_operations: {
194
+ ...TOOL_METADATA.list_operations,
195
+ handler: (args: ListOperationsArgs) => {
196
+ const result = introspector.listOperations(args.id);
197
+ const shaped = shapeListOperations(result, pickListOptions(args));
198
+ log({ tool: 'list_operations', args, count: result.length, truncated: shaped.truncated });
199
+ return shaped;
200
+ },
201
+ } satisfies ToolDefinition<ListOperationsArgs>,
202
+
203
+ list_schemas: {
204
+ ...TOOL_METADATA.list_schemas,
205
+ handler: (args: ListSchemasArgs) => {
206
+ const result = introspector.listSchemas(args.id);
207
+ const shaped = shapeListSchemas(result, pickListOptions(args));
208
+ log({ tool: 'list_schemas', args, count: result.length, truncated: shaped.truncated });
209
+ return shaped;
210
+ },
211
+ } satisfies ToolDefinition<ListSchemasArgs>,
212
+ });