@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.
- package/README.md +212 -0
- package/bin/dx-introspect-mcp.mjs +11 -0
- package/dist/lib/node-esm/chunk-63HTIHM3.mjs +400 -0
- package/dist/lib/node-esm/chunk-63HTIHM3.mjs.map +7 -0
- package/dist/lib/node-esm/index.mjs +270 -0
- package/dist/lib/node-esm/index.mjs.map +7 -0
- package/dist/lib/node-esm/meta.json +1 -0
- package/dist/lib/node-esm/tools/index.mjs +34 -0
- package/dist/lib/node-esm/tools/index.mjs.map +7 -0
- package/dist/types/src/cli.d.ts +2 -0
- package/dist/types/src/cli.d.ts.map +1 -0
- package/dist/types/src/index.d.ts +3 -0
- package/dist/types/src/index.d.ts.map +1 -0
- package/dist/types/src/server/http.test.d.ts +2 -0
- package/dist/types/src/server/http.test.d.ts.map +1 -0
- package/dist/types/src/server/index.d.ts +3 -0
- package/dist/types/src/server/index.d.ts.map +1 -0
- package/dist/types/src/server/main.d.ts +2 -0
- package/dist/types/src/server/main.d.ts.map +1 -0
- package/dist/types/src/server/server.d.ts +14 -0
- package/dist/types/src/server/server.d.ts.map +1 -0
- package/dist/types/src/server/server.test.d.ts +2 -0
- package/dist/types/src/server/server.test.d.ts.map +1 -0
- package/dist/types/src/server/stdio.test.d.ts +2 -0
- package/dist/types/src/server/stdio.test.d.ts.map +1 -0
- package/dist/types/src/tools/index.d.ts +4 -0
- package/dist/types/src/tools/index.d.ts.map +1 -0
- package/dist/types/src/tools/logger.d.ts +20 -0
- package/dist/types/src/tools/logger.d.ts.map +1 -0
- package/dist/types/src/tools/shaping.d.ts +24 -0
- package/dist/types/src/tools/shaping.d.ts.map +1 -0
- package/dist/types/src/tools/tools.d.ts +38 -0
- package/dist/types/src/tools/tools.d.ts.map +1 -0
- package/dist/types/src/tools/tools.test.d.ts +2 -0
- package/dist/types/src/tools/tools.test.d.ts.map +1 -0
- package/dist/types/tsconfig.tsbuildinfo +1 -0
- package/package.json +53 -0
- package/src/cli.ts +13 -0
- package/src/index.ts +10 -0
- package/src/server/http.test.ts +89 -0
- package/src/server/index.ts +10 -0
- package/src/server/main.ts +275 -0
- package/src/server/server.test.ts +215 -0
- package/src/server/server.ts +79 -0
- package/src/server/stdio.test.ts +76 -0
- package/src/tools/index.ts +28 -0
- package/src/tools/logger.ts +60 -0
- package/src/tools/shaping.ts +194 -0
- package/src/tools/tools.test.ts +78 -0
- 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
|
+
});
|