@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,79 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
6
|
+
|
|
7
|
+
import type { Introspector } from '@dxos/introspect';
|
|
8
|
+
import { inputSchemaToZod } from '@dxos/introspect-tools';
|
|
9
|
+
|
|
10
|
+
import { createToolDefinitions, registerLogger, type ToolLogger, type ToolResult } from '../tools';
|
|
11
|
+
|
|
12
|
+
export type ServerOptions = {
|
|
13
|
+
introspector: Introspector;
|
|
14
|
+
/** Server name advertised over MCP. */
|
|
15
|
+
name?: string;
|
|
16
|
+
/** Server version advertised over MCP. */
|
|
17
|
+
version?: string;
|
|
18
|
+
/** Optional logger; defaults to a no-op. */
|
|
19
|
+
logger?: ToolLogger;
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
type McpToolResult = { content: Array<{ type: 'text'; text: string }> };
|
|
23
|
+
|
|
24
|
+
export const createServer = (options: ServerOptions): McpServer => {
|
|
25
|
+
const { introspector } = options;
|
|
26
|
+
const log = registerLogger(options.logger);
|
|
27
|
+
|
|
28
|
+
const server = new McpServer({
|
|
29
|
+
name: options.name ?? '@dxos/introspect-mcp',
|
|
30
|
+
version: options.version ?? '0.0.0',
|
|
31
|
+
});
|
|
32
|
+
|
|
33
|
+
// Every tool handler is wrapped with `withReady` so it blocks on indexing
|
|
34
|
+
// before running — but ONLY when the handler runs. `initialize` and
|
|
35
|
+
// `tools/list` are answered by the SDK from the static tool registry below,
|
|
36
|
+
// so MCP clients (Inspector, Claude Code, Composer) connect immediately
|
|
37
|
+
// even on a cold cache. Cold-start cost is paid once, on the first
|
|
38
|
+
// `tools/call`. Centralizing this in a wrapper means a future tool can't
|
|
39
|
+
// accidentally skip the readiness gate by forgetting the await.
|
|
40
|
+
const withReady =
|
|
41
|
+
<TArgs>(handler: (args: TArgs) => ToolResult | Promise<ToolResult>) =>
|
|
42
|
+
async (args: TArgs): Promise<McpToolResult> => {
|
|
43
|
+
await introspector.ready;
|
|
44
|
+
const shaped = await handler(args);
|
|
45
|
+
return toToolResult(shaped);
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
// Tool metadata + handlers live in `tools.ts`. This server is just the
|
|
49
|
+
// wiring: register each tool from the map, converting its Effect Schema
|
|
50
|
+
// input to zod (the MCP SDK's required form), gating handlers behind
|
|
51
|
+
// `withReady`, and wrapping their `ToolResult` in the MCP content envelope.
|
|
52
|
+
const definitions = createToolDefinitions(introspector, log);
|
|
53
|
+
for (const [name, def] of Object.entries(definitions)) {
|
|
54
|
+
server.registerTool(
|
|
55
|
+
name,
|
|
56
|
+
{
|
|
57
|
+
title: def.title,
|
|
58
|
+
description: def.description,
|
|
59
|
+
inputSchema: inputSchemaToZod(def.inputSchema),
|
|
60
|
+
},
|
|
61
|
+
withReady(def.handler),
|
|
62
|
+
);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
return server;
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
const toToolResult = (shaped: ToolResult): McpToolResult => {
|
|
69
|
+
const payload: Record<string, unknown> = { data: shaped.data };
|
|
70
|
+
if (shaped.note) {
|
|
71
|
+
payload.note = shaped.note;
|
|
72
|
+
}
|
|
73
|
+
if (shaped.truncated) {
|
|
74
|
+
payload.truncated = shaped.truncated;
|
|
75
|
+
}
|
|
76
|
+
return {
|
|
77
|
+
content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
|
|
78
|
+
};
|
|
79
|
+
};
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
// End-to-end stdio integration test: spawn the actual CLI as a subprocess via
|
|
6
|
+
// `StdioClientTransport` and exercise it through real pipes. Catches issues
|
|
7
|
+
// the in-memory transport in `server.test.ts` cannot — stdout pollution,
|
|
8
|
+
// `--conditions=source` resolution, exports-field mishaps, framing, and
|
|
9
|
+
// process startup failures.
|
|
10
|
+
|
|
11
|
+
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
|
12
|
+
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
|
|
13
|
+
import { dirname, join } from 'node:path';
|
|
14
|
+
import { fileURLToPath } from 'node:url';
|
|
15
|
+
import { afterAll, beforeAll, describe, test } from 'vitest';
|
|
16
|
+
|
|
17
|
+
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
18
|
+
// cli.ts lives at src/cli.ts (kept at the package's public entry path so
|
|
19
|
+
// .mcp.json / moon tasks / scripts can keep referencing it unchanged).
|
|
20
|
+
const CLI_PATH = join(__dirname, '..', 'cli.ts');
|
|
21
|
+
const FIXTURE_ROOT = join(__dirname, '..', '..', '..', 'introspect', 'src', '__fixtures__');
|
|
22
|
+
|
|
23
|
+
describe('stdio integration', () => {
|
|
24
|
+
let client: Client;
|
|
25
|
+
|
|
26
|
+
beforeAll(async () => {
|
|
27
|
+
// tsx + --conditions=source is exactly how end users launch the server in
|
|
28
|
+
// dev. If something about that resolution path breaks, this test catches it.
|
|
29
|
+
const transport = new StdioClientTransport({
|
|
30
|
+
command: 'npx',
|
|
31
|
+
args: ['tsx', '--conditions=source', CLI_PATH, '--root', FIXTURE_ROOT],
|
|
32
|
+
});
|
|
33
|
+
client = new Client({ name: 'stdio-probe', version: 'test' }, { capabilities: {} });
|
|
34
|
+
await client.connect(transport);
|
|
35
|
+
}, 60_000);
|
|
36
|
+
|
|
37
|
+
afterAll(async () => {
|
|
38
|
+
await client?.close();
|
|
39
|
+
});
|
|
40
|
+
|
|
41
|
+
test('subprocess starts and lists every registered tool', async ({ expect }) => {
|
|
42
|
+
const { tools } = await client.listTools();
|
|
43
|
+
const names = tools.map((t) => t.name).sort();
|
|
44
|
+
expect(names).toEqual([
|
|
45
|
+
'find_symbol',
|
|
46
|
+
'get_package',
|
|
47
|
+
'get_symbol',
|
|
48
|
+
'list_capabilities',
|
|
49
|
+
'list_operations',
|
|
50
|
+
'list_packages',
|
|
51
|
+
'list_plugins',
|
|
52
|
+
'list_schemas',
|
|
53
|
+
'list_surfaces',
|
|
54
|
+
'list_symbols',
|
|
55
|
+
]);
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
test('list_packages round-trips real JSON-RPC over stdio', async ({ expect }) => {
|
|
59
|
+
const result = (await client.callTool({ name: 'list_packages', arguments: {} })) as {
|
|
60
|
+
content: Array<{ type: string; text?: string }>;
|
|
61
|
+
};
|
|
62
|
+
const text = result.content.find((c) => c.type === 'text')?.text ?? '';
|
|
63
|
+
const payload = JSON.parse(text) as { data: Array<{ name: string }> };
|
|
64
|
+
expect(payload.data.map((p) => p.name)).toContain('@fixture/pkg-a');
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
test('find_symbol locates the ECHO Task across the stdio boundary', async ({ expect }) => {
|
|
68
|
+
const result = (await client.callTool({
|
|
69
|
+
name: 'find_symbol',
|
|
70
|
+
arguments: { query: 'Task' },
|
|
71
|
+
})) as { content: Array<{ type: string; text?: string }> };
|
|
72
|
+
const text = result.content.find((c) => c.type === 'text')?.text ?? '';
|
|
73
|
+
const payload = JSON.parse(text) as { data: Array<{ ref: string }> };
|
|
74
|
+
expect(payload.data.some((m) => m.ref === '@fixture/pkg-a#Task')).toBe(true);
|
|
75
|
+
});
|
|
76
|
+
});
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
// Server-side handler factory + response shapers + logger interface —
|
|
6
|
+
// everything callers need to plug DXOS introspection into an MCP-compatible
|
|
7
|
+
// host without pulling in the stdio/HTTP server machinery.
|
|
8
|
+
//
|
|
9
|
+
// Schema input definitions and `TOOL_METADATA` live in `@dxos/introspect-tools`
|
|
10
|
+
// (browser-safe contract); import them from there directly.
|
|
11
|
+
//
|
|
12
|
+
// Importable as `@dxos/introspect-mcp/tools` (see package.json `exports`).
|
|
13
|
+
|
|
14
|
+
export { createToolDefinitions, type ToolDefinition } from './tools';
|
|
15
|
+
export {
|
|
16
|
+
shapeFindSymbol,
|
|
17
|
+
shapeGetPackage,
|
|
18
|
+
shapeGetSymbol,
|
|
19
|
+
shapeListCapabilities,
|
|
20
|
+
shapeListOperations,
|
|
21
|
+
shapeListPackages,
|
|
22
|
+
shapeListPlugins,
|
|
23
|
+
shapeListSchemas,
|
|
24
|
+
shapeListSurfaces,
|
|
25
|
+
shapePluginDetail,
|
|
26
|
+
type ToolResult,
|
|
27
|
+
} from './shaping';
|
|
28
|
+
export { fileLogger, noopLogger, registerLogger, type ToolLogEntry, type ToolLogger } from './logger';
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
// Tool-call logging — drives future tool prioritization.
|
|
6
|
+
//
|
|
7
|
+
// Every tool call is logged; failed structured queries that fall through to
|
|
8
|
+
// search_code (when added in a later phase) get logged separately. This is
|
|
9
|
+
// intentionally minimal — appending JSONL is enough for the analysis we want
|
|
10
|
+
// to do later, and keeps the runtime dependency surface small.
|
|
11
|
+
|
|
12
|
+
import { appendFile, mkdir } from 'node:fs/promises';
|
|
13
|
+
import { dirname } from 'node:path';
|
|
14
|
+
|
|
15
|
+
export type ToolLogEntry = {
|
|
16
|
+
tool: string;
|
|
17
|
+
args?: unknown;
|
|
18
|
+
count?: number;
|
|
19
|
+
found?: boolean;
|
|
20
|
+
truncated?: string;
|
|
21
|
+
};
|
|
22
|
+
|
|
23
|
+
export type ToolLogger = (entry: ToolLogEntry) => void;
|
|
24
|
+
|
|
25
|
+
export const noopLogger: ToolLogger = () => {};
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Wrap a logger so failures inside it never throw into the caller. Returns the
|
|
29
|
+
* wrapped logger; if `inner` is undefined, returns a no-op. Timestamp injection
|
|
30
|
+
* is the responsibility of concrete sinks (see `fileLogger`).
|
|
31
|
+
*/
|
|
32
|
+
export const registerLogger = (inner?: ToolLogger): ToolLogger => {
|
|
33
|
+
if (!inner) {
|
|
34
|
+
return noopLogger;
|
|
35
|
+
}
|
|
36
|
+
return (entry) => {
|
|
37
|
+
try {
|
|
38
|
+
inner(entry);
|
|
39
|
+
} catch {
|
|
40
|
+
// Logger failures must not break tool calls.
|
|
41
|
+
}
|
|
42
|
+
};
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Append-only JSONL logger. Creates the parent directory on first write.
|
|
47
|
+
*/
|
|
48
|
+
export const fileLogger = (path: string): ToolLogger => {
|
|
49
|
+
let ensured = false;
|
|
50
|
+
return (entry) => {
|
|
51
|
+
const line = `${JSON.stringify({ ts: new Date().toISOString(), ...entry })}\n`;
|
|
52
|
+
void (async () => {
|
|
53
|
+
if (!ensured) {
|
|
54
|
+
await mkdir(dirname(path), { recursive: true });
|
|
55
|
+
ensured = true;
|
|
56
|
+
}
|
|
57
|
+
await appendFile(path, line, 'utf8');
|
|
58
|
+
})().catch(() => undefined);
|
|
59
|
+
};
|
|
60
|
+
};
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
// Response shaping for token budgets.
|
|
6
|
+
//
|
|
7
|
+
// Tool responses target a sane default size for the LLM context (~30 list
|
|
8
|
+
// items, single-record fetches kept compact via `include` opt-ins). Callers
|
|
9
|
+
// that legitimately need a longer list pass `limit`; callers in "discovery
|
|
10
|
+
// mode" (just want to see what exists) pass `compact: true` for a refs/ids-
|
|
11
|
+
// only projection at roughly 1/4 the wire size.
|
|
12
|
+
|
|
13
|
+
import type {
|
|
14
|
+
Capability,
|
|
15
|
+
Operation,
|
|
16
|
+
Package,
|
|
17
|
+
PackageDetail,
|
|
18
|
+
Plugin,
|
|
19
|
+
PluginDetail,
|
|
20
|
+
Schema,
|
|
21
|
+
Surface,
|
|
22
|
+
SymbolDetail,
|
|
23
|
+
SymbolMatch,
|
|
24
|
+
} from '@dxos/introspect';
|
|
25
|
+
import { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, type ListOptions } from '@dxos/introspect-tools';
|
|
26
|
+
|
|
27
|
+
const SOURCE_PREVIEW = 1200;
|
|
28
|
+
const JSDOC_PREVIEW = 600;
|
|
29
|
+
|
|
30
|
+
export type ToolResult = {
|
|
31
|
+
data: unknown;
|
|
32
|
+
note?: string;
|
|
33
|
+
truncated?: string;
|
|
34
|
+
};
|
|
35
|
+
|
|
36
|
+
type ShapeListConfig<T> = {
|
|
37
|
+
/** Full projection — what an LLM gets when `compact` is false/omitted. */
|
|
38
|
+
full: (item: T) => Record<string, unknown>;
|
|
39
|
+
/** Compact projection — ids / typenames / names only. */
|
|
40
|
+
compact: (item: T) => Record<string, unknown>;
|
|
41
|
+
/** Suffix for the `truncated` note: "<N> more results — <hint>". */
|
|
42
|
+
truncationHint: string;
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
const shapeList = <T>(all: readonly T[], opts: ListOptions, config: ShapeListConfig<T>): ToolResult => {
|
|
46
|
+
const requested = opts.limit ?? DEFAULT_LIST_LIMIT;
|
|
47
|
+
const limit = Math.min(Math.max(0, Math.floor(requested)), MAX_LIST_LIMIT);
|
|
48
|
+
const project = opts.compact ? config.compact : config.full;
|
|
49
|
+
const data = all.slice(0, limit).map(project);
|
|
50
|
+
if (all.length > limit) {
|
|
51
|
+
return {
|
|
52
|
+
data,
|
|
53
|
+
truncated: `${all.length - limit} more results — ${config.truncationHint}`,
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
return { data };
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
//
|
|
60
|
+
// Packages
|
|
61
|
+
//
|
|
62
|
+
|
|
63
|
+
export const shapeListPackages = (all: Package[], opts: ListOptions = {}): ToolResult =>
|
|
64
|
+
shapeList(all, opts, {
|
|
65
|
+
full: (p) => ({
|
|
66
|
+
name: p.name,
|
|
67
|
+
version: p.version,
|
|
68
|
+
private: p.private,
|
|
69
|
+
path: p.path,
|
|
70
|
+
description: p.description,
|
|
71
|
+
}),
|
|
72
|
+
compact: (p) => ({ name: p.name, path: p.path }),
|
|
73
|
+
truncationHint: 'raise `limit` (max 200), refine with `name`/`pathPrefix`, or call get_package directly.',
|
|
74
|
+
});
|
|
75
|
+
|
|
76
|
+
export const shapeGetPackage = (detail: PackageDetail): ToolResult => ({
|
|
77
|
+
data: {
|
|
78
|
+
name: detail.name,
|
|
79
|
+
version: detail.version,
|
|
80
|
+
private: detail.private,
|
|
81
|
+
path: detail.path,
|
|
82
|
+
description: detail.description,
|
|
83
|
+
workspaceDependencies: detail.workspaceDependencies,
|
|
84
|
+
externalDependencies: detail.externalDependencies,
|
|
85
|
+
entryPoints: detail.entryPoints,
|
|
86
|
+
// Surfaced so callers can decide whether to call find_symbol against this package.
|
|
87
|
+
exportCount: detail.exportCount,
|
|
88
|
+
},
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
//
|
|
92
|
+
// Symbols
|
|
93
|
+
//
|
|
94
|
+
|
|
95
|
+
export const shapeFindSymbol = (matches: SymbolMatch[], opts: ListOptions = {}): ToolResult =>
|
|
96
|
+
shapeList(matches, opts, {
|
|
97
|
+
full: (m) => ({ ref: m.ref, name: m.name, package: m.package, kind: m.kind, summary: m.summary }),
|
|
98
|
+
compact: (m) => ({ ref: m.ref, name: m.name }),
|
|
99
|
+
truncationHint: 'raise `limit` (max 200), refine the query, or filter by `kind`.',
|
|
100
|
+
});
|
|
101
|
+
|
|
102
|
+
export const shapeGetSymbol = (detail: SymbolDetail): ToolResult => {
|
|
103
|
+
const result: Record<string, unknown> = {
|
|
104
|
+
ref: detail.ref,
|
|
105
|
+
package: detail.package,
|
|
106
|
+
name: detail.name,
|
|
107
|
+
kind: detail.kind,
|
|
108
|
+
signature: detail.signature,
|
|
109
|
+
summary: detail.summary,
|
|
110
|
+
location: detail.location,
|
|
111
|
+
};
|
|
112
|
+
if (detail.jsdoc) {
|
|
113
|
+
result.jsdoc = truncate(detail.jsdoc, JSDOC_PREVIEW);
|
|
114
|
+
}
|
|
115
|
+
if (detail.source !== undefined) {
|
|
116
|
+
result.source = truncate(detail.source, SOURCE_PREVIEW);
|
|
117
|
+
}
|
|
118
|
+
return { data: result };
|
|
119
|
+
};
|
|
120
|
+
|
|
121
|
+
const truncate = (s: string, limit: number): string => {
|
|
122
|
+
if (s.length <= limit) {
|
|
123
|
+
return s;
|
|
124
|
+
}
|
|
125
|
+
return `${s.slice(0, limit)}\n... (truncated, ${s.length - limit} more chars)`;
|
|
126
|
+
};
|
|
127
|
+
|
|
128
|
+
//
|
|
129
|
+
// Plugin / surface / capability / operation / schema (main's flatter types)
|
|
130
|
+
//
|
|
131
|
+
|
|
132
|
+
export const shapeListPlugins = (all: Plugin[], opts: ListOptions = {}): ToolResult =>
|
|
133
|
+
shapeList(all, opts, {
|
|
134
|
+
full: (p) => ({
|
|
135
|
+
id: p.id,
|
|
136
|
+
package: p.package,
|
|
137
|
+
name: p.name,
|
|
138
|
+
description: p.description,
|
|
139
|
+
icon: p.icon,
|
|
140
|
+
iconHue: p.iconHue,
|
|
141
|
+
}),
|
|
142
|
+
compact: (p) => ({ id: p.id, name: p.name }),
|
|
143
|
+
truncationHint: 'raise `limit` (max 200) or filter with `id` substring.',
|
|
144
|
+
});
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* `PluginDetail` is the same shape as `Plugin` plus arrays of contributions.
|
|
148
|
+
* Returned by what would be `get_plugin` if the introspector exposed it; we
|
|
149
|
+
* synthesize this on the MCP side by combining `listPlugins` + the per-id
|
|
150
|
+
* `listSurfaces` / `listCapabilities` / `listOperations` / `listSchemas` calls.
|
|
151
|
+
*/
|
|
152
|
+
export const shapePluginDetail = (detail: PluginDetail): ToolResult => ({
|
|
153
|
+
data: {
|
|
154
|
+
id: detail.id,
|
|
155
|
+
package: detail.package,
|
|
156
|
+
name: detail.name,
|
|
157
|
+
description: detail.description,
|
|
158
|
+
icon: detail.icon,
|
|
159
|
+
iconHue: detail.iconHue,
|
|
160
|
+
metaLocation: detail.metaLocation,
|
|
161
|
+
surfaces: detail.surfaces.map((s) => ({ id: s.id, role: s.role })),
|
|
162
|
+
capabilities: detail.capabilities.map((c) => ({ type: c.type })),
|
|
163
|
+
operations: detail.operations.map((o) => ({ type: o.type })),
|
|
164
|
+
schemas: detail.schemas.map((s) => ({ name: s.name, typename: s.typename })),
|
|
165
|
+
},
|
|
166
|
+
});
|
|
167
|
+
|
|
168
|
+
export const shapeListSurfaces = (all: Surface[], opts: ListOptions = {}): ToolResult =>
|
|
169
|
+
shapeList(all, opts, {
|
|
170
|
+
full: (s) => ({ pluginId: s.pluginId, id: s.id, role: s.role, location: s.location }),
|
|
171
|
+
compact: (s) => ({ pluginId: s.pluginId, id: s.id }),
|
|
172
|
+
truncationHint: 'raise `limit` (max 200) or filter by plugin `id`.',
|
|
173
|
+
});
|
|
174
|
+
|
|
175
|
+
export const shapeListCapabilities = (all: Capability[], opts: ListOptions = {}): ToolResult =>
|
|
176
|
+
shapeList(all, opts, {
|
|
177
|
+
full: (c) => ({ pluginId: c.pluginId, type: c.type, location: c.location }),
|
|
178
|
+
compact: (c) => ({ pluginId: c.pluginId, type: c.type }),
|
|
179
|
+
truncationHint: 'raise `limit` (max 200) or filter by plugin `id`.',
|
|
180
|
+
});
|
|
181
|
+
|
|
182
|
+
export const shapeListOperations = (all: Operation[], opts: ListOptions = {}): ToolResult =>
|
|
183
|
+
shapeList(all, opts, {
|
|
184
|
+
full: (o) => ({ pluginId: o.pluginId, type: o.type, location: o.location }),
|
|
185
|
+
compact: (o) => ({ pluginId: o.pluginId, type: o.type }),
|
|
186
|
+
truncationHint: 'raise `limit` (max 200) or filter by plugin `id`.',
|
|
187
|
+
});
|
|
188
|
+
|
|
189
|
+
export const shapeListSchemas = (all: Schema[], opts: ListOptions = {}): ToolResult =>
|
|
190
|
+
shapeList(all, opts, {
|
|
191
|
+
full: (s) => ({ pluginId: s.pluginId, name: s.name, typename: s.typename, location: s.location }),
|
|
192
|
+
compact: (s) => ({ pluginId: s.pluginId, name: s.name, typename: s.typename }),
|
|
193
|
+
truncationHint: 'raise `limit` (max 200) or filter by plugin `id`.',
|
|
194
|
+
});
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
// Verifies the `@dxos/introspect-mcp/tools` subpath export resolves and
|
|
6
|
+
// produces the expected tool surface without dragging in the stdio/HTTP
|
|
7
|
+
// server. A separate consumer (e.g. plugin-assistant) embedding these tools
|
|
8
|
+
// in a different MCP runtime should be able to import only this entry point.
|
|
9
|
+
//
|
|
10
|
+
// The test deliberately imports via the package name (not relative paths) so
|
|
11
|
+
// it fails if the `exports['./tools']` field in package.json regresses.
|
|
12
|
+
|
|
13
|
+
import { dirname, join } from 'node:path';
|
|
14
|
+
import { fileURLToPath } from 'node:url';
|
|
15
|
+
import { describe, test } from 'vitest';
|
|
16
|
+
|
|
17
|
+
import { createIntrospector } from '@dxos/introspect';
|
|
18
|
+
import { createToolDefinitions, noopLogger } from '@dxos/introspect-mcp/tools';
|
|
19
|
+
|
|
20
|
+
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
21
|
+
// `<this file>/../../../introspect/src/__fixtures__`. Reused so the
|
|
22
|
+
// subpath import test sees the same fixture set as the rest of the suite.
|
|
23
|
+
const FIXTURE_ROOT = join(__dirname, '..', '..', '..', 'introspect', 'src', '__fixtures__');
|
|
24
|
+
|
|
25
|
+
// CI runners are slower than local; ts-morph indexing the 2-package fixture
|
|
26
|
+
// takes ~4s on the GitHub runner, blowing past vitest's 5s default. Bump
|
|
27
|
+
// the per-test timeout for both tests in this suite.
|
|
28
|
+
describe('@dxos/introspect-mcp/tools subpath export', { timeout: 30_000 }, () => {
|
|
29
|
+
test('createToolDefinitions returns the full 10-tool map', async ({ expect }) => {
|
|
30
|
+
const introspector = createIntrospector({ rootPath: FIXTURE_ROOT, cache: false });
|
|
31
|
+
await introspector.ready;
|
|
32
|
+
try {
|
|
33
|
+
const definitions = createToolDefinitions(introspector, noopLogger);
|
|
34
|
+
const names = Object.keys(definitions).sort();
|
|
35
|
+
expect(names).toEqual([
|
|
36
|
+
'find_symbol',
|
|
37
|
+
'get_package',
|
|
38
|
+
'get_symbol',
|
|
39
|
+
'list_capabilities',
|
|
40
|
+
'list_operations',
|
|
41
|
+
'list_packages',
|
|
42
|
+
'list_plugins',
|
|
43
|
+
'list_schemas',
|
|
44
|
+
'list_surfaces',
|
|
45
|
+
'list_symbols',
|
|
46
|
+
]);
|
|
47
|
+
// Every entry must carry the metadata MCP wants from a tool definition.
|
|
48
|
+
// `inputSchema` is an Effect `Schema.Struct(...)` (which is callable —
|
|
49
|
+
// hence `function` typeof) carrying a `.fields` record. The server
|
|
50
|
+
// converts it to zod via `inputSchemaToZod` at registration time.
|
|
51
|
+
for (const def of Object.values(definitions)) {
|
|
52
|
+
expect(typeof def.title).toBe('string');
|
|
53
|
+
expect(typeof def.description).toBe('string');
|
|
54
|
+
expect(def.inputSchema).toBeDefined();
|
|
55
|
+
expect(typeof (def.inputSchema as { fields?: unknown }).fields).toBe('object');
|
|
56
|
+
expect(typeof def.handler).toBe('function');
|
|
57
|
+
}
|
|
58
|
+
} finally {
|
|
59
|
+
introspector.dispose();
|
|
60
|
+
}
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
test('handlers run end-to-end without the MCP server wiring', async ({ expect }) => {
|
|
64
|
+
// Embedding scenario: a different runtime calls a handler directly,
|
|
65
|
+
// bypassing the readiness gate / MCP envelope. We await `ready` here on
|
|
66
|
+
// behalf of that runtime so the handler sees a populated index.
|
|
67
|
+
const introspector = createIntrospector({ rootPath: FIXTURE_ROOT, cache: false });
|
|
68
|
+
await introspector.ready;
|
|
69
|
+
try {
|
|
70
|
+
const { list_packages } = createToolDefinitions(introspector, noopLogger);
|
|
71
|
+
const result = await list_packages.handler({});
|
|
72
|
+
const data = result.data as Array<{ name: string }>;
|
|
73
|
+
expect(data.some((p) => p.name === '@fixture/pkg-a')).toBe(true);
|
|
74
|
+
} finally {
|
|
75
|
+
introspector.dispose();
|
|
76
|
+
}
|
|
77
|
+
});
|
|
78
|
+
});
|