@dxos/introspect-tools 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.
@@ -0,0 +1,215 @@
1
+ import "@dxos/node-std/globals";
2
+
3
+ // src/limits.ts
4
+ var DEFAULT_LIST_LIMIT = 30;
5
+ var MAX_LIST_LIMIT = 200;
6
+
7
+ // src/metadata.ts
8
+ import { effectFieldsToZod } from "@dxos/effect-zod";
9
+ import { trim as trim2 } from "@dxos/util";
10
+
11
+ // src/schemas.ts
12
+ import * as Schema from "effect/Schema";
13
+ import { trim } from "@dxos/util";
14
+ var ListOptionsInput = Schema.Struct({
15
+ limit: Schema.optional(Schema.Number.pipe(Schema.int(), Schema.positive(), Schema.lessThanOrEqualTo(MAX_LIST_LIMIT))).annotations({
16
+ title: "Limit",
17
+ description: trim`
18
+ Maximum number of items to return. Default ${DEFAULT_LIST_LIMIT}; max ${MAX_LIST_LIMIT}.
19
+ `
20
+ }),
21
+ compact: Schema.optional(Schema.Boolean).annotations({
22
+ title: "Compact",
23
+ description: trim`
24
+ If true, returns only the most-essential identifying fields for each item — about 1/4 the response size.
25
+ Use when discovering what exists before drilling in.
26
+ `
27
+ })
28
+ });
29
+ var SymbolKindEnum = Schema.Literal("function", "class", "interface", "type", "enum", "variable", "namespace");
30
+ var IncludeEnum = Schema.Literal("source", "jsdoc");
31
+ var ListPackagesInput = Schema.Struct({
32
+ name: Schema.optional(Schema.String).annotations({
33
+ title: "Name filter",
34
+ description: "Substring of the package name (case-insensitive)."
35
+ }),
36
+ pathPrefix: Schema.optional(Schema.String).annotations({
37
+ title: "Path prefix",
38
+ description: 'Restrict to packages whose path starts with this segment, e.g. "packages/plugins".'
39
+ }),
40
+ privateOnly: Schema.optional(Schema.Boolean).annotations({
41
+ title: "Private only",
42
+ description: "If true, only include workspace-private packages."
43
+ }),
44
+ ...ListOptionsInput.fields
45
+ });
46
+ var GetPackageInput = Schema.Struct({
47
+ name: Schema.String.annotations({
48
+ title: "Package name",
49
+ description: 'Exact package name, e.g. "@dxos/echo".'
50
+ })
51
+ });
52
+ var ListSymbolsInput = Schema.Struct({
53
+ package: Schema.String.annotations({
54
+ title: "Package",
55
+ description: 'Exact package name, e.g. "@dxos/ai".'
56
+ }),
57
+ kind: Schema.optional(SymbolKindEnum).annotations({
58
+ title: "Kind",
59
+ description: "Optional filter on declaration kind."
60
+ }),
61
+ ...ListOptionsInput.fields
62
+ });
63
+ var FindSymbolInput = Schema.Struct({
64
+ query: Schema.String.annotations({
65
+ title: "Query",
66
+ description: "Symbol name or partial name (case-insensitive)."
67
+ }),
68
+ kind: Schema.optional(SymbolKindEnum).annotations({
69
+ title: "Kind",
70
+ description: "Optional filter on declaration kind."
71
+ }),
72
+ ...ListOptionsInput.fields
73
+ });
74
+ var GetSymbolInput = Schema.Struct({
75
+ ref: Schema.String.annotations({
76
+ title: "Symbol ref",
77
+ description: 'Symbol ref in the form "<package>#<name>", e.g. "@dxos/echo#Expando".'
78
+ }),
79
+ include: Schema.optional(Schema.Array(IncludeEnum)).annotations({
80
+ title: "Include",
81
+ description: "Optional fields to expand; default returns signature + summary only."
82
+ })
83
+ });
84
+ var ListPluginsInput = Schema.Struct({
85
+ id: Schema.optional(Schema.String).annotations({
86
+ title: "Plugin id",
87
+ description: "Substring of the plugin id (case-insensitive). Omit to list every plugin."
88
+ }),
89
+ ...ListOptionsInput.fields
90
+ });
91
+ var PluginIdFilter = Schema.Struct({
92
+ id: Schema.optional(Schema.String).annotations({
93
+ title: "Plugin id",
94
+ description: 'Restrict to contributions from this plugin id (e.g. "org.dxos.plugin.markdown").'
95
+ }),
96
+ ...ListOptionsInput.fields
97
+ });
98
+ var ListSurfacesInput = PluginIdFilter;
99
+ var ListCapabilitiesInput = PluginIdFilter;
100
+ var ListOperationsInput = PluginIdFilter;
101
+ var ListSchemasInput = PluginIdFilter;
102
+
103
+ // src/metadata.ts
104
+ var TOOL_METADATA = {
105
+ list_packages: {
106
+ title: "List monorepo packages",
107
+ description: trim2`
108
+ List packages in the DXOS monorepo. Use this to discover what packages exist before drilling into one.
109
+ Supports filtering by name substring, path prefix (e.g. "packages/plugins"), or workspace-private only.
110
+ Returns lightweight rows; call get_package for dependency and entry-point detail.
111
+ `,
112
+ inputSchema: ListPackagesInput
113
+ },
114
+ get_package: {
115
+ title: "Get package detail",
116
+ description: trim2`
117
+ Fetch the full record for a single package by its name (e.g. "@dxos/echo").
118
+ Returns workspace and external dependencies, entry points, and metadata.
119
+ Use after list_packages or when the user references a package directly.
120
+ `,
121
+ inputSchema: GetPackageInput
122
+ },
123
+ list_symbols: {
124
+ title: "List all exported symbols of a package",
125
+ description: trim2`
126
+ Enumerate every exported symbol declared by a single package (e.g. all exports of "@dxos/echo-react").
127
+ Use this when the user wants to know what a specific package offers, or to browse a package after get_package.
128
+ Returns lightweight rows with refs you can pass to get_symbol; capped at 30 — refine with \`kind\` or call get_symbol directly.
129
+ `,
130
+ inputSchema: ListSymbolsInput
131
+ },
132
+ find_symbol: {
133
+ title: "Find an exported symbol by name",
134
+ description: trim2`
135
+ Find an exported symbol (function, class, type, hook, schema) by name or partial name across all DXOS packages.
136
+ Use this when the user references something by name and you need to locate which package owns it before reading more.
137
+ Returns refs you can pass to get_symbol. Ranking: exact match, then prefix, then substring.
138
+ `,
139
+ inputSchema: FindSymbolInput
140
+ },
141
+ get_symbol: {
142
+ title: "Get symbol detail",
143
+ description: trim2`
144
+ Fetch detail for a single symbol by ref (e.g. "@dxos/echo#Expando").
145
+ Default response is signature + JSDoc summary + source location.
146
+ Pass include=["source"] to expand the full declaration text, include=["jsdoc"] for the full JSDoc body.
147
+ `,
148
+ inputSchema: GetSymbolInput
149
+ },
150
+ list_plugins: {
151
+ title: "List Composer plugins",
152
+ description: trim2`
153
+ List plugins detected in the monorepo. A plugin is a package whose src/meta.ts exports a \`Plugin.Meta\`.
154
+ Use this to discover what plugins exist before drilling into surfaces / capabilities / operations / schemas.
155
+ Filter by \`id\` substring (e.g. "markdown") to narrow the list.
156
+ `,
157
+ inputSchema: ListPluginsInput
158
+ },
159
+ list_surfaces: {
160
+ title: "List surfaces",
161
+ description: trim2`
162
+ List Surface.create({ id, role, ... }) contributions across the monorepo. Use this to discover available
163
+ surface ids when wiring a new container, or to check whether a surface name is already taken.
164
+ Filter by \`id\` (plugin id) to scope to a single plugin's surfaces.
165
+ `,
166
+ inputSchema: ListSurfacesInput
167
+ },
168
+ list_capabilities: {
169
+ title: "List capability contributions",
170
+ description: trim2`
171
+ List Capability.contributes(<key>, ...) calls across the monorepo. Use this to discover which capability
172
+ keys are produced (or required) by which plugins. Filter by \`id\` (plugin id) to scope to a single plugin.
173
+ `,
174
+ inputSchema: ListCapabilitiesInput
175
+ },
176
+ list_operations: {
177
+ title: "List operations",
178
+ description: trim2`
179
+ List operations contributed by plugins. An *operation* is a serializable
180
+ request (verb + payload) dispatched through the OperationInvoker —
181
+ Composer's equivalent of an action / command. Most plugins contribute
182
+ these via \`Capabilities.OperationHandler\`. Filter by \`id\` (plugin id)
183
+ to scope to a single plugin.
184
+ `,
185
+ inputSchema: ListOperationsInput
186
+ },
187
+ list_schemas: {
188
+ title: "List schemas",
189
+ description: trim2`
190
+ List ECHO-registered types contributed by plugins (declared via addSchemaModule).
191
+ Use this to discover what data types exist before reading their shape.
192
+ Filter by \`id\` (plugin id, e.g. "org.dxos.plugin.markdown") to scope to a single plugin's schemas.
193
+ `,
194
+ inputSchema: ListSchemasInput
195
+ }
196
+ };
197
+ var inputSchemaToZod = (struct) => effectFieldsToZod(struct);
198
+ export {
199
+ DEFAULT_LIST_LIMIT,
200
+ FindSymbolInput,
201
+ GetPackageInput,
202
+ GetSymbolInput,
203
+ ListCapabilitiesInput,
204
+ ListOperationsInput,
205
+ ListOptionsInput,
206
+ ListPackagesInput,
207
+ ListPluginsInput,
208
+ ListSchemasInput,
209
+ ListSurfacesInput,
210
+ ListSymbolsInput,
211
+ MAX_LIST_LIMIT,
212
+ TOOL_METADATA,
213
+ inputSchemaToZod
214
+ };
215
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../../../src/limits.ts", "../../../src/metadata.ts", "../../../src/schemas.ts"],
4
+ "sourcesContent": ["//\n// Copyright 2026 DXOS.org\n//\n\n// Shared list-pagination constants used by both the schema definitions\n// (`Schema.lessThanOrEqualTo(MAX_LIST_LIMIT)` on every list tool's `limit`\n// field) and by the server-side response shapers in @dxos/introspect-mcp.\n// Lives here so the contract surface (introspect-tools) doesn't have to\n// import from the runtime package.\n\n/** Default number of items returned by list-style tools when no `limit` is passed. */\nexport const DEFAULT_LIST_LIMIT = 30;\n\n/**\n * Hard ceiling on `limit`. A runaway tool call shouldn't be able to dump every\n * symbol in the monorepo (~thousands) into the model's context. Callers who\n * truly need everything should iterate via filters (pluginId, package, etc.).\n */\nexport const MAX_LIST_LIMIT = 200;\n\n/**\n * Per-call options every list-style tool accepts. Both fields are optional\n * — the defaults match `DEFAULT_LIST_LIMIT` items, full projection.\n */\nexport type ListOptions = {\n /** Override the default `DEFAULT_LIST_LIMIT`. Capped at `MAX_LIST_LIMIT`. */\n limit?: number;\n /**\n * Return only the most-essential identifying fields (ref/id/name) instead\n * of the full record. Use when discovering what exists before drilling in\n * with a `get_*` call. Roughly 1/4 the token cost.\n */\n compact?: boolean;\n};\n", "//\n// Copyright 2026 DXOS.org\n//\n\n// Static tool metadata + the Effect Schema → Zod adapter for the MCP SDK.\n//\n// Pure data + a stateless converter — no introspector, no Node-only deps,\n// no MCP SDK. The introspect-mcp server consumes this map at startup to\n// register each tool with a handler closing over its `Introspector`;\n// browser-side consumers (react-ui-introspect, etc.) consume the same map\n// to render forms / lists / docs from a single source of truth.\n\nimport * as Schema from 'effect/Schema';\nimport type { z } from 'zod';\n\nimport { effectFieldsToZod } from '@dxos/effect-zod';\nimport { trim } from '@dxos/util';\n\nimport {\n FindSymbolInput,\n GetPackageInput,\n GetSymbolInput,\n ListCapabilitiesInput,\n ListOperationsInput,\n ListPackagesInput,\n ListPluginsInput,\n ListSchemasInput,\n ListSurfacesInput,\n ListSymbolsInput,\n} from './schemas';\n\n/**\n * Pure metadata for a single MCP tool — what an MCP client needs to know\n * before invoking it: human-readable title, an LLM-targeted description,\n * and the Effect Schema input contract.\n */\nexport type ToolMetadata = {\n /** Human-readable title surfaced by Inspector / Composer. */\n title: string;\n\n /**\n * LLM-targeted description. Models read this to decide WHEN to call the\n * tool — write it for trigger accuracy, not for human reading. State both\n * what the tool does and the situations it's the right answer for.\n */\n description: string;\n\n /**\n * Effect Schema struct describing the tool's input. Server-side, the\n * MCP SDK requires zod, so the server converts to zod via\n * `inputSchemaToZod` at registration time. Browser consumers\n * (react-ui-form, etc.) use this directly.\n */\n inputSchema: Schema.Struct<any>;\n};\n\n/**\n * Static metadata for every tool the introspect-mcp server exposes. No\n * introspector or runtime state — safe to import from a browser bundle.\n *\n * Adding a tool means: (1) define its input schema in `./schemas.ts`,\n * (2) add an entry here, (3) add a matching handler in\n * `@dxos/introspect-mcp` that closes over a runtime `Introspector`.\n */\nexport const TOOL_METADATA: Record<string, ToolMetadata> = {\n list_packages: {\n title: 'List monorepo packages',\n description: trim`\n List packages in the DXOS monorepo. Use this to discover what packages exist before drilling into one.\n Supports filtering by name substring, path prefix (e.g. \"packages/plugins\"), or workspace-private only.\n Returns lightweight rows; call get_package for dependency and entry-point detail.\n `,\n inputSchema: ListPackagesInput,\n },\n get_package: {\n title: 'Get package detail',\n description: trim`\n Fetch the full record for a single package by its name (e.g. \"@dxos/echo\").\n Returns workspace and external dependencies, entry points, and metadata.\n Use after list_packages or when the user references a package directly.\n `,\n inputSchema: GetPackageInput,\n },\n list_symbols: {\n title: 'List all exported symbols of a package',\n description: trim`\n Enumerate every exported symbol declared by a single package (e.g. all exports of \"@dxos/echo-react\").\n Use this when the user wants to know what a specific package offers, or to browse a package after get_package.\n Returns lightweight rows with refs you can pass to get_symbol; capped at 30 — refine with \\`kind\\` or call get_symbol directly.\n `,\n inputSchema: ListSymbolsInput,\n },\n find_symbol: {\n title: 'Find an exported symbol by name',\n description: trim`\n Find an exported symbol (function, class, type, hook, schema) by name or partial name across all DXOS packages.\n Use this when the user references something by name and you need to locate which package owns it before reading more.\n Returns refs you can pass to get_symbol. Ranking: exact match, then prefix, then substring.\n `,\n inputSchema: FindSymbolInput,\n },\n get_symbol: {\n title: 'Get symbol detail',\n description: trim`\n Fetch detail for a single symbol by ref (e.g. \"@dxos/echo#Expando\").\n Default response is signature + JSDoc summary + source location.\n Pass include=[\"source\"] to expand the full declaration text, include=[\"jsdoc\"] for the full JSDoc body.\n `,\n inputSchema: GetSymbolInput,\n },\n list_plugins: {\n title: 'List Composer plugins',\n description: trim`\n List plugins detected in the monorepo. A plugin is a package whose src/meta.ts exports a \\`Plugin.Meta\\`.\n Use this to discover what plugins exist before drilling into surfaces / capabilities / operations / schemas.\n Filter by \\`id\\` substring (e.g. \"markdown\") to narrow the list.\n `,\n inputSchema: ListPluginsInput,\n },\n list_surfaces: {\n title: 'List surfaces',\n description: trim`\n List Surface.create({ id, role, ... }) contributions across the monorepo. Use this to discover available\n surface ids when wiring a new container, or to check whether a surface name is already taken.\n Filter by \\`id\\` (plugin id) to scope to a single plugin's surfaces.\n `,\n inputSchema: ListSurfacesInput,\n },\n list_capabilities: {\n title: 'List capability contributions',\n description: trim`\n List Capability.contributes(<key>, ...) calls across the monorepo. Use this to discover which capability\n keys are produced (or required) by which plugins. Filter by \\`id\\` (plugin id) to scope to a single plugin.\n `,\n inputSchema: ListCapabilitiesInput,\n },\n list_operations: {\n title: 'List operations',\n description: trim`\n List operations contributed by plugins. An *operation* is a serializable\n request (verb + payload) dispatched through the OperationInvoker —\n Composer's equivalent of an action / command. Most plugins contribute\n these via \\`Capabilities.OperationHandler\\`. Filter by \\`id\\` (plugin id)\n to scope to a single plugin.\n `,\n inputSchema: ListOperationsInput,\n },\n list_schemas: {\n title: 'List schemas',\n description: trim`\n List ECHO-registered types contributed by plugins (declared via addSchemaModule).\n Use this to discover what data types exist before reading their shape.\n Filter by \\`id\\` (plugin id, e.g. \"org.dxos.plugin.markdown\") to scope to a single plugin's schemas.\n `,\n inputSchema: ListSchemasInput,\n },\n};\n\n/**\n * Materialize a tool's `inputSchema` (Effect Struct) into the\n * `Record<string, z.ZodTypeAny>` shape the MCP SDK's `registerTool` requires.\n * Called once per tool at server startup; throws with a clear message if a\n * tool's input uses a schema pattern the converter doesn't support.\n */\nexport const inputSchemaToZod = (struct: Schema.Struct<any>): Record<string, z.ZodTypeAny> => effectFieldsToZod(struct);\n", "//\n// Copyright 2026 DXOS.org\n//\n\n// Effect Schema input definitions for every MCP tool.\n//\n// These are the source of truth: `@dxos/introspect-mcp` converts them to zod\n// at registration time (the MCP SDK requires zod), and downstream consumers\n// like `react-ui-form` import them directly to render forms.\n//\n// Convention: every field's description goes on the OUTERMOST wrapper.\n// - Optional fields: `.annotations({ description })` on `Schema.optional(...)`.\n// - Required fields: `.annotations({ description })` on the primitive itself.\n\nimport * as Schema from 'effect/Schema';\n\nimport { trim } from '@dxos/util';\n\nimport { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from './limits';\n\n/**\n * Pagination + projection options shared by every list-style tool. Spread its\n * `.fields` into a tool's `Schema.Struct({...})` so the same pair of knobs\n * appears on every list endpoint without copy-paste.\n *\n * The default behavior (no `limit`, no `compact`) matches the old hard-cap-of-30\n * shape, so callers that don't pass these args see no change.\n */\nexport const ListOptionsInput = Schema.Struct({\n limit: Schema.optional(\n Schema.Number.pipe(Schema.int(), Schema.positive(), Schema.lessThanOrEqualTo(MAX_LIST_LIMIT)),\n ).annotations({\n title: 'Limit',\n description: trim`\n Maximum number of items to return. Default ${DEFAULT_LIST_LIMIT}; max ${MAX_LIST_LIMIT}.\n `,\n }),\n compact: Schema.optional(Schema.Boolean).annotations({\n title: 'Compact',\n description: trim`\n If true, returns only the most-essential identifying fields for each item — about 1/4 the response size.\n Use when discovering what exists before drilling in.\n `,\n }),\n});\n\nconst SymbolKindEnum = Schema.Literal('function', 'class', 'interface', 'type', 'enum', 'variable', 'namespace');\n\nconst IncludeEnum = Schema.Literal('source', 'jsdoc');\n\n//\n// Packages\n//\n\nexport const ListPackagesInput = Schema.Struct({\n name: Schema.optional(Schema.String).annotations({\n title: 'Name filter',\n description: 'Substring of the package name (case-insensitive).',\n }),\n pathPrefix: Schema.optional(Schema.String).annotations({\n title: 'Path prefix',\n description: 'Restrict to packages whose path starts with this segment, e.g. \"packages/plugins\".',\n }),\n privateOnly: Schema.optional(Schema.Boolean).annotations({\n title: 'Private only',\n description: 'If true, only include workspace-private packages.',\n }),\n ...ListOptionsInput.fields,\n});\n\nexport const GetPackageInput = Schema.Struct({\n name: Schema.String.annotations({\n title: 'Package name',\n description: 'Exact package name, e.g. \"@dxos/echo\".',\n }),\n});\n\n//\n// Symbols\n//\n\nexport const ListSymbolsInput = Schema.Struct({\n package: Schema.String.annotations({\n title: 'Package',\n description: 'Exact package name, e.g. \"@dxos/ai\".',\n }),\n kind: Schema.optional(SymbolKindEnum).annotations({\n title: 'Kind',\n description: 'Optional filter on declaration kind.',\n }),\n ...ListOptionsInput.fields,\n});\n\nexport const FindSymbolInput = Schema.Struct({\n query: Schema.String.annotations({\n title: 'Query',\n description: 'Symbol name or partial name (case-insensitive).',\n }),\n kind: Schema.optional(SymbolKindEnum).annotations({\n title: 'Kind',\n description: 'Optional filter on declaration kind.',\n }),\n ...ListOptionsInput.fields,\n});\n\nexport const GetSymbolInput = Schema.Struct({\n ref: Schema.String.annotations({\n title: 'Symbol ref',\n description: 'Symbol ref in the form \"<package>#<name>\", e.g. \"@dxos/echo#Expando\".',\n }),\n include: Schema.optional(Schema.Array(IncludeEnum)).annotations({\n title: 'Include',\n description: 'Optional fields to expand; default returns signature + summary only.',\n }),\n});\n\n//\n// Plugins / surfaces / capabilities / operations / schemas\n//\n// Main's API exposes a single optional `id` filter on each of these — the\n// plugin id (e.g. \"org.dxos.plugin.markdown\"). `listPlugins` accepts a\n// `PluginFilter` object with `id` for substring matching.\n//\n\nexport const ListPluginsInput = Schema.Struct({\n id: Schema.optional(Schema.String).annotations({\n title: 'Plugin id',\n description: 'Substring of the plugin id (case-insensitive). Omit to list every plugin.',\n }),\n ...ListOptionsInput.fields,\n});\n\nconst PluginIdFilter = Schema.Struct({\n id: Schema.optional(Schema.String).annotations({\n title: 'Plugin id',\n description: 'Restrict to contributions from this plugin id (e.g. \"org.dxos.plugin.markdown\").',\n }),\n ...ListOptionsInput.fields,\n});\n\nexport const ListSurfacesInput = PluginIdFilter;\nexport const ListCapabilitiesInput = PluginIdFilter;\nexport const ListOperationsInput = PluginIdFilter;\nexport const ListSchemasInput = PluginIdFilter;\n\n//\n// Inferred TypeScript types — handy for downstream consumers.\n//\n\nexport type ListPackagesArgs = typeof ListPackagesInput.Type;\nexport type GetPackageArgs = typeof GetPackageInput.Type;\nexport type ListSymbolsArgs = typeof ListSymbolsInput.Type;\nexport type FindSymbolArgs = typeof FindSymbolInput.Type;\nexport type GetSymbolArgs = typeof GetSymbolInput.Type;\nexport type ListPluginsArgs = typeof ListPluginsInput.Type;\nexport type ListSurfacesArgs = typeof ListSurfacesInput.Type;\nexport type ListCapabilitiesArgs = typeof ListCapabilitiesInput.Type;\nexport type ListOperationsArgs = typeof ListOperationsInput.Type;\nexport type ListSchemasArgs = typeof ListSchemasInput.Type;\n"],
5
+ "mappings": "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",
6
+ "names": ["DEFAULT_LIST_LIMIT", "MAX_LIST_LIMIT", "effectFieldsToZod", "trim", "Schema", "trim", "ListOptionsInput", "Struct", "limit", "optional", "Number", "pipe", "int", "positive", "lessThanOrEqualTo", "MAX_LIST_LIMIT", "annotations", "title", "description", "trim", "DEFAULT_LIST_LIMIT", "compact", "Boolean", "SymbolKindEnum", "Literal", "IncludeEnum", "ListPackagesInput", "name", "String", "pathPrefix", "privateOnly", "fields", "GetPackageInput", "ListSymbolsInput", "package", "kind", "FindSymbolInput", "query", "GetSymbolInput", "ref", "include", "Array", "ListPluginsInput", "id", "PluginIdFilter", "ListSurfacesInput", "ListCapabilitiesInput", "ListOperationsInput", "ListSchemasInput", "TOOL_METADATA", "list_packages", "title", "description", "trim", "inputSchema", "ListPackagesInput", "get_package", "GetPackageInput", "list_symbols", "ListSymbolsInput", "find_symbol", "FindSymbolInput", "get_symbol", "GetSymbolInput", "list_plugins", "ListPluginsInput", "list_surfaces", "ListSurfacesInput", "list_capabilities", "ListCapabilitiesInput", "list_operations", "ListOperationsInput", "list_schemas", "ListSchemasInput", "inputSchemaToZod", "struct", "effectFieldsToZod"]
7
+ }
@@ -0,0 +1 @@
1
+ {"inputs":{"src/limits.ts":{"bytes":3000,"imports":[],"format":"esm"},"src/schemas.ts":{"bytes":16540,"imports":[{"path":"effect/Schema","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"src/limits.ts","kind":"import-statement","original":"./limits"}],"format":"esm"},"src/metadata.ts":{"bytes":17520,"imports":[{"path":"@dxos/effect-zod","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"src/schemas.ts","kind":"import-statement","original":"./schemas"}],"format":"esm"},"src/index.ts":{"bytes":2842,"imports":[{"path":"src/limits.ts","kind":"import-statement","original":"./limits"},{"path":"src/metadata.ts","kind":"import-statement","original":"./metadata"},{"path":"src/schemas.ts","kind":"import-statement","original":"./schemas"}],"format":"esm"}},"outputs":{"dist/lib/browser/index.mjs.map":{"imports":[],"exports":[],"inputs":{},"bytes":17625},"dist/lib/browser/index.mjs":{"imports":[{"path":"@dxos/effect-zod","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"effect/Schema","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true}],"exports":["DEFAULT_LIST_LIMIT","FindSymbolInput","GetPackageInput","GetSymbolInput","ListCapabilitiesInput","ListOperationsInput","ListOptionsInput","ListPackagesInput","ListPluginsInput","ListSchemasInput","ListSurfacesInput","ListSymbolsInput","MAX_LIST_LIMIT","TOOL_METADATA","inputSchemaToZod"],"entryPoint":"src/index.ts","inputs":{"src/limits.ts":{"bytesInOutput":55},"src/index.ts":{"bytesInOutput":0},"src/metadata.ts":{"bytesInOutput":4372},"src/schemas.ts":{"bytesInOutput":3311}},"bytes":8197}}}
@@ -0,0 +1,215 @@
1
+ import { createRequire } from 'node:module';const require = createRequire(import.meta.url);
2
+
3
+ // src/limits.ts
4
+ var DEFAULT_LIST_LIMIT = 30;
5
+ var MAX_LIST_LIMIT = 200;
6
+
7
+ // src/metadata.ts
8
+ import { effectFieldsToZod } from "@dxos/effect-zod";
9
+ import { trim as trim2 } from "@dxos/util";
10
+
11
+ // src/schemas.ts
12
+ import * as Schema from "effect/Schema";
13
+ import { trim } from "@dxos/util";
14
+ var ListOptionsInput = Schema.Struct({
15
+ limit: Schema.optional(Schema.Number.pipe(Schema.int(), Schema.positive(), Schema.lessThanOrEqualTo(MAX_LIST_LIMIT))).annotations({
16
+ title: "Limit",
17
+ description: trim`
18
+ Maximum number of items to return. Default ${DEFAULT_LIST_LIMIT}; max ${MAX_LIST_LIMIT}.
19
+ `
20
+ }),
21
+ compact: Schema.optional(Schema.Boolean).annotations({
22
+ title: "Compact",
23
+ description: trim`
24
+ If true, returns only the most-essential identifying fields for each item — about 1/4 the response size.
25
+ Use when discovering what exists before drilling in.
26
+ `
27
+ })
28
+ });
29
+ var SymbolKindEnum = Schema.Literal("function", "class", "interface", "type", "enum", "variable", "namespace");
30
+ var IncludeEnum = Schema.Literal("source", "jsdoc");
31
+ var ListPackagesInput = Schema.Struct({
32
+ name: Schema.optional(Schema.String).annotations({
33
+ title: "Name filter",
34
+ description: "Substring of the package name (case-insensitive)."
35
+ }),
36
+ pathPrefix: Schema.optional(Schema.String).annotations({
37
+ title: "Path prefix",
38
+ description: 'Restrict to packages whose path starts with this segment, e.g. "packages/plugins".'
39
+ }),
40
+ privateOnly: Schema.optional(Schema.Boolean).annotations({
41
+ title: "Private only",
42
+ description: "If true, only include workspace-private packages."
43
+ }),
44
+ ...ListOptionsInput.fields
45
+ });
46
+ var GetPackageInput = Schema.Struct({
47
+ name: Schema.String.annotations({
48
+ title: "Package name",
49
+ description: 'Exact package name, e.g. "@dxos/echo".'
50
+ })
51
+ });
52
+ var ListSymbolsInput = Schema.Struct({
53
+ package: Schema.String.annotations({
54
+ title: "Package",
55
+ description: 'Exact package name, e.g. "@dxos/ai".'
56
+ }),
57
+ kind: Schema.optional(SymbolKindEnum).annotations({
58
+ title: "Kind",
59
+ description: "Optional filter on declaration kind."
60
+ }),
61
+ ...ListOptionsInput.fields
62
+ });
63
+ var FindSymbolInput = Schema.Struct({
64
+ query: Schema.String.annotations({
65
+ title: "Query",
66
+ description: "Symbol name or partial name (case-insensitive)."
67
+ }),
68
+ kind: Schema.optional(SymbolKindEnum).annotations({
69
+ title: "Kind",
70
+ description: "Optional filter on declaration kind."
71
+ }),
72
+ ...ListOptionsInput.fields
73
+ });
74
+ var GetSymbolInput = Schema.Struct({
75
+ ref: Schema.String.annotations({
76
+ title: "Symbol ref",
77
+ description: 'Symbol ref in the form "<package>#<name>", e.g. "@dxos/echo#Expando".'
78
+ }),
79
+ include: Schema.optional(Schema.Array(IncludeEnum)).annotations({
80
+ title: "Include",
81
+ description: "Optional fields to expand; default returns signature + summary only."
82
+ })
83
+ });
84
+ var ListPluginsInput = Schema.Struct({
85
+ id: Schema.optional(Schema.String).annotations({
86
+ title: "Plugin id",
87
+ description: "Substring of the plugin id (case-insensitive). Omit to list every plugin."
88
+ }),
89
+ ...ListOptionsInput.fields
90
+ });
91
+ var PluginIdFilter = Schema.Struct({
92
+ id: Schema.optional(Schema.String).annotations({
93
+ title: "Plugin id",
94
+ description: 'Restrict to contributions from this plugin id (e.g. "org.dxos.plugin.markdown").'
95
+ }),
96
+ ...ListOptionsInput.fields
97
+ });
98
+ var ListSurfacesInput = PluginIdFilter;
99
+ var ListCapabilitiesInput = PluginIdFilter;
100
+ var ListOperationsInput = PluginIdFilter;
101
+ var ListSchemasInput = PluginIdFilter;
102
+
103
+ // src/metadata.ts
104
+ var TOOL_METADATA = {
105
+ list_packages: {
106
+ title: "List monorepo packages",
107
+ description: trim2`
108
+ List packages in the DXOS monorepo. Use this to discover what packages exist before drilling into one.
109
+ Supports filtering by name substring, path prefix (e.g. "packages/plugins"), or workspace-private only.
110
+ Returns lightweight rows; call get_package for dependency and entry-point detail.
111
+ `,
112
+ inputSchema: ListPackagesInput
113
+ },
114
+ get_package: {
115
+ title: "Get package detail",
116
+ description: trim2`
117
+ Fetch the full record for a single package by its name (e.g. "@dxos/echo").
118
+ Returns workspace and external dependencies, entry points, and metadata.
119
+ Use after list_packages or when the user references a package directly.
120
+ `,
121
+ inputSchema: GetPackageInput
122
+ },
123
+ list_symbols: {
124
+ title: "List all exported symbols of a package",
125
+ description: trim2`
126
+ Enumerate every exported symbol declared by a single package (e.g. all exports of "@dxos/echo-react").
127
+ Use this when the user wants to know what a specific package offers, or to browse a package after get_package.
128
+ Returns lightweight rows with refs you can pass to get_symbol; capped at 30 — refine with \`kind\` or call get_symbol directly.
129
+ `,
130
+ inputSchema: ListSymbolsInput
131
+ },
132
+ find_symbol: {
133
+ title: "Find an exported symbol by name",
134
+ description: trim2`
135
+ Find an exported symbol (function, class, type, hook, schema) by name or partial name across all DXOS packages.
136
+ Use this when the user references something by name and you need to locate which package owns it before reading more.
137
+ Returns refs you can pass to get_symbol. Ranking: exact match, then prefix, then substring.
138
+ `,
139
+ inputSchema: FindSymbolInput
140
+ },
141
+ get_symbol: {
142
+ title: "Get symbol detail",
143
+ description: trim2`
144
+ Fetch detail for a single symbol by ref (e.g. "@dxos/echo#Expando").
145
+ Default response is signature + JSDoc summary + source location.
146
+ Pass include=["source"] to expand the full declaration text, include=["jsdoc"] for the full JSDoc body.
147
+ `,
148
+ inputSchema: GetSymbolInput
149
+ },
150
+ list_plugins: {
151
+ title: "List Composer plugins",
152
+ description: trim2`
153
+ List plugins detected in the monorepo. A plugin is a package whose src/meta.ts exports a \`Plugin.Meta\`.
154
+ Use this to discover what plugins exist before drilling into surfaces / capabilities / operations / schemas.
155
+ Filter by \`id\` substring (e.g. "markdown") to narrow the list.
156
+ `,
157
+ inputSchema: ListPluginsInput
158
+ },
159
+ list_surfaces: {
160
+ title: "List surfaces",
161
+ description: trim2`
162
+ List Surface.create({ id, role, ... }) contributions across the monorepo. Use this to discover available
163
+ surface ids when wiring a new container, or to check whether a surface name is already taken.
164
+ Filter by \`id\` (plugin id) to scope to a single plugin's surfaces.
165
+ `,
166
+ inputSchema: ListSurfacesInput
167
+ },
168
+ list_capabilities: {
169
+ title: "List capability contributions",
170
+ description: trim2`
171
+ List Capability.contributes(<key>, ...) calls across the monorepo. Use this to discover which capability
172
+ keys are produced (or required) by which plugins. Filter by \`id\` (plugin id) to scope to a single plugin.
173
+ `,
174
+ inputSchema: ListCapabilitiesInput
175
+ },
176
+ list_operations: {
177
+ title: "List operations",
178
+ description: trim2`
179
+ List operations contributed by plugins. An *operation* is a serializable
180
+ request (verb + payload) dispatched through the OperationInvoker —
181
+ Composer's equivalent of an action / command. Most plugins contribute
182
+ these via \`Capabilities.OperationHandler\`. Filter by \`id\` (plugin id)
183
+ to scope to a single plugin.
184
+ `,
185
+ inputSchema: ListOperationsInput
186
+ },
187
+ list_schemas: {
188
+ title: "List schemas",
189
+ description: trim2`
190
+ List ECHO-registered types contributed by plugins (declared via addSchemaModule).
191
+ Use this to discover what data types exist before reading their shape.
192
+ Filter by \`id\` (plugin id, e.g. "org.dxos.plugin.markdown") to scope to a single plugin's schemas.
193
+ `,
194
+ inputSchema: ListSchemasInput
195
+ }
196
+ };
197
+ var inputSchemaToZod = (struct) => effectFieldsToZod(struct);
198
+ export {
199
+ DEFAULT_LIST_LIMIT,
200
+ FindSymbolInput,
201
+ GetPackageInput,
202
+ GetSymbolInput,
203
+ ListCapabilitiesInput,
204
+ ListOperationsInput,
205
+ ListOptionsInput,
206
+ ListPackagesInput,
207
+ ListPluginsInput,
208
+ ListSchemasInput,
209
+ ListSurfacesInput,
210
+ ListSymbolsInput,
211
+ MAX_LIST_LIMIT,
212
+ TOOL_METADATA,
213
+ inputSchemaToZod
214
+ };
215
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../../../src/limits.ts", "../../../src/metadata.ts", "../../../src/schemas.ts"],
4
+ "sourcesContent": ["//\n// Copyright 2026 DXOS.org\n//\n\n// Shared list-pagination constants used by both the schema definitions\n// (`Schema.lessThanOrEqualTo(MAX_LIST_LIMIT)` on every list tool's `limit`\n// field) and by the server-side response shapers in @dxos/introspect-mcp.\n// Lives here so the contract surface (introspect-tools) doesn't have to\n// import from the runtime package.\n\n/** Default number of items returned by list-style tools when no `limit` is passed. */\nexport const DEFAULT_LIST_LIMIT = 30;\n\n/**\n * Hard ceiling on `limit`. A runaway tool call shouldn't be able to dump every\n * symbol in the monorepo (~thousands) into the model's context. Callers who\n * truly need everything should iterate via filters (pluginId, package, etc.).\n */\nexport const MAX_LIST_LIMIT = 200;\n\n/**\n * Per-call options every list-style tool accepts. Both fields are optional\n * — the defaults match `DEFAULT_LIST_LIMIT` items, full projection.\n */\nexport type ListOptions = {\n /** Override the default `DEFAULT_LIST_LIMIT`. Capped at `MAX_LIST_LIMIT`. */\n limit?: number;\n /**\n * Return only the most-essential identifying fields (ref/id/name) instead\n * of the full record. Use when discovering what exists before drilling in\n * with a `get_*` call. Roughly 1/4 the token cost.\n */\n compact?: boolean;\n};\n", "//\n// Copyright 2026 DXOS.org\n//\n\n// Static tool metadata + the Effect Schema → Zod adapter for the MCP SDK.\n//\n// Pure data + a stateless converter — no introspector, no Node-only deps,\n// no MCP SDK. The introspect-mcp server consumes this map at startup to\n// register each tool with a handler closing over its `Introspector`;\n// browser-side consumers (react-ui-introspect, etc.) consume the same map\n// to render forms / lists / docs from a single source of truth.\n\nimport * as Schema from 'effect/Schema';\nimport type { z } from 'zod';\n\nimport { effectFieldsToZod } from '@dxos/effect-zod';\nimport { trim } from '@dxos/util';\n\nimport {\n FindSymbolInput,\n GetPackageInput,\n GetSymbolInput,\n ListCapabilitiesInput,\n ListOperationsInput,\n ListPackagesInput,\n ListPluginsInput,\n ListSchemasInput,\n ListSurfacesInput,\n ListSymbolsInput,\n} from './schemas';\n\n/**\n * Pure metadata for a single MCP tool — what an MCP client needs to know\n * before invoking it: human-readable title, an LLM-targeted description,\n * and the Effect Schema input contract.\n */\nexport type ToolMetadata = {\n /** Human-readable title surfaced by Inspector / Composer. */\n title: string;\n\n /**\n * LLM-targeted description. Models read this to decide WHEN to call the\n * tool — write it for trigger accuracy, not for human reading. State both\n * what the tool does and the situations it's the right answer for.\n */\n description: string;\n\n /**\n * Effect Schema struct describing the tool's input. Server-side, the\n * MCP SDK requires zod, so the server converts to zod via\n * `inputSchemaToZod` at registration time. Browser consumers\n * (react-ui-form, etc.) use this directly.\n */\n inputSchema: Schema.Struct<any>;\n};\n\n/**\n * Static metadata for every tool the introspect-mcp server exposes. No\n * introspector or runtime state — safe to import from a browser bundle.\n *\n * Adding a tool means: (1) define its input schema in `./schemas.ts`,\n * (2) add an entry here, (3) add a matching handler in\n * `@dxos/introspect-mcp` that closes over a runtime `Introspector`.\n */\nexport const TOOL_METADATA: Record<string, ToolMetadata> = {\n list_packages: {\n title: 'List monorepo packages',\n description: trim`\n List packages in the DXOS monorepo. Use this to discover what packages exist before drilling into one.\n Supports filtering by name substring, path prefix (e.g. \"packages/plugins\"), or workspace-private only.\n Returns lightweight rows; call get_package for dependency and entry-point detail.\n `,\n inputSchema: ListPackagesInput,\n },\n get_package: {\n title: 'Get package detail',\n description: trim`\n Fetch the full record for a single package by its name (e.g. \"@dxos/echo\").\n Returns workspace and external dependencies, entry points, and metadata.\n Use after list_packages or when the user references a package directly.\n `,\n inputSchema: GetPackageInput,\n },\n list_symbols: {\n title: 'List all exported symbols of a package',\n description: trim`\n Enumerate every exported symbol declared by a single package (e.g. all exports of \"@dxos/echo-react\").\n Use this when the user wants to know what a specific package offers, or to browse a package after get_package.\n Returns lightweight rows with refs you can pass to get_symbol; capped at 30 — refine with \\`kind\\` or call get_symbol directly.\n `,\n inputSchema: ListSymbolsInput,\n },\n find_symbol: {\n title: 'Find an exported symbol by name',\n description: trim`\n Find an exported symbol (function, class, type, hook, schema) by name or partial name across all DXOS packages.\n Use this when the user references something by name and you need to locate which package owns it before reading more.\n Returns refs you can pass to get_symbol. Ranking: exact match, then prefix, then substring.\n `,\n inputSchema: FindSymbolInput,\n },\n get_symbol: {\n title: 'Get symbol detail',\n description: trim`\n Fetch detail for a single symbol by ref (e.g. \"@dxos/echo#Expando\").\n Default response is signature + JSDoc summary + source location.\n Pass include=[\"source\"] to expand the full declaration text, include=[\"jsdoc\"] for the full JSDoc body.\n `,\n inputSchema: GetSymbolInput,\n },\n list_plugins: {\n title: 'List Composer plugins',\n description: trim`\n List plugins detected in the monorepo. A plugin is a package whose src/meta.ts exports a \\`Plugin.Meta\\`.\n Use this to discover what plugins exist before drilling into surfaces / capabilities / operations / schemas.\n Filter by \\`id\\` substring (e.g. \"markdown\") to narrow the list.\n `,\n inputSchema: ListPluginsInput,\n },\n list_surfaces: {\n title: 'List surfaces',\n description: trim`\n List Surface.create({ id, role, ... }) contributions across the monorepo. Use this to discover available\n surface ids when wiring a new container, or to check whether a surface name is already taken.\n Filter by \\`id\\` (plugin id) to scope to a single plugin's surfaces.\n `,\n inputSchema: ListSurfacesInput,\n },\n list_capabilities: {\n title: 'List capability contributions',\n description: trim`\n List Capability.contributes(<key>, ...) calls across the monorepo. Use this to discover which capability\n keys are produced (or required) by which plugins. Filter by \\`id\\` (plugin id) to scope to a single plugin.\n `,\n inputSchema: ListCapabilitiesInput,\n },\n list_operations: {\n title: 'List operations',\n description: trim`\n List operations contributed by plugins. An *operation* is a serializable\n request (verb + payload) dispatched through the OperationInvoker —\n Composer's equivalent of an action / command. Most plugins contribute\n these via \\`Capabilities.OperationHandler\\`. Filter by \\`id\\` (plugin id)\n to scope to a single plugin.\n `,\n inputSchema: ListOperationsInput,\n },\n list_schemas: {\n title: 'List schemas',\n description: trim`\n List ECHO-registered types contributed by plugins (declared via addSchemaModule).\n Use this to discover what data types exist before reading their shape.\n Filter by \\`id\\` (plugin id, e.g. \"org.dxos.plugin.markdown\") to scope to a single plugin's schemas.\n `,\n inputSchema: ListSchemasInput,\n },\n};\n\n/**\n * Materialize a tool's `inputSchema` (Effect Struct) into the\n * `Record<string, z.ZodTypeAny>` shape the MCP SDK's `registerTool` requires.\n * Called once per tool at server startup; throws with a clear message if a\n * tool's input uses a schema pattern the converter doesn't support.\n */\nexport const inputSchemaToZod = (struct: Schema.Struct<any>): Record<string, z.ZodTypeAny> => effectFieldsToZod(struct);\n", "//\n// Copyright 2026 DXOS.org\n//\n\n// Effect Schema input definitions for every MCP tool.\n//\n// These are the source of truth: `@dxos/introspect-mcp` converts them to zod\n// at registration time (the MCP SDK requires zod), and downstream consumers\n// like `react-ui-form` import them directly to render forms.\n//\n// Convention: every field's description goes on the OUTERMOST wrapper.\n// - Optional fields: `.annotations({ description })` on `Schema.optional(...)`.\n// - Required fields: `.annotations({ description })` on the primitive itself.\n\nimport * as Schema from 'effect/Schema';\n\nimport { trim } from '@dxos/util';\n\nimport { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from './limits';\n\n/**\n * Pagination + projection options shared by every list-style tool. Spread its\n * `.fields` into a tool's `Schema.Struct({...})` so the same pair of knobs\n * appears on every list endpoint without copy-paste.\n *\n * The default behavior (no `limit`, no `compact`) matches the old hard-cap-of-30\n * shape, so callers that don't pass these args see no change.\n */\nexport const ListOptionsInput = Schema.Struct({\n limit: Schema.optional(\n Schema.Number.pipe(Schema.int(), Schema.positive(), Schema.lessThanOrEqualTo(MAX_LIST_LIMIT)),\n ).annotations({\n title: 'Limit',\n description: trim`\n Maximum number of items to return. Default ${DEFAULT_LIST_LIMIT}; max ${MAX_LIST_LIMIT}.\n `,\n }),\n compact: Schema.optional(Schema.Boolean).annotations({\n title: 'Compact',\n description: trim`\n If true, returns only the most-essential identifying fields for each item — about 1/4 the response size.\n Use when discovering what exists before drilling in.\n `,\n }),\n});\n\nconst SymbolKindEnum = Schema.Literal('function', 'class', 'interface', 'type', 'enum', 'variable', 'namespace');\n\nconst IncludeEnum = Schema.Literal('source', 'jsdoc');\n\n//\n// Packages\n//\n\nexport const ListPackagesInput = Schema.Struct({\n name: Schema.optional(Schema.String).annotations({\n title: 'Name filter',\n description: 'Substring of the package name (case-insensitive).',\n }),\n pathPrefix: Schema.optional(Schema.String).annotations({\n title: 'Path prefix',\n description: 'Restrict to packages whose path starts with this segment, e.g. \"packages/plugins\".',\n }),\n privateOnly: Schema.optional(Schema.Boolean).annotations({\n title: 'Private only',\n description: 'If true, only include workspace-private packages.',\n }),\n ...ListOptionsInput.fields,\n});\n\nexport const GetPackageInput = Schema.Struct({\n name: Schema.String.annotations({\n title: 'Package name',\n description: 'Exact package name, e.g. \"@dxos/echo\".',\n }),\n});\n\n//\n// Symbols\n//\n\nexport const ListSymbolsInput = Schema.Struct({\n package: Schema.String.annotations({\n title: 'Package',\n description: 'Exact package name, e.g. \"@dxos/ai\".',\n }),\n kind: Schema.optional(SymbolKindEnum).annotations({\n title: 'Kind',\n description: 'Optional filter on declaration kind.',\n }),\n ...ListOptionsInput.fields,\n});\n\nexport const FindSymbolInput = Schema.Struct({\n query: Schema.String.annotations({\n title: 'Query',\n description: 'Symbol name or partial name (case-insensitive).',\n }),\n kind: Schema.optional(SymbolKindEnum).annotations({\n title: 'Kind',\n description: 'Optional filter on declaration kind.',\n }),\n ...ListOptionsInput.fields,\n});\n\nexport const GetSymbolInput = Schema.Struct({\n ref: Schema.String.annotations({\n title: 'Symbol ref',\n description: 'Symbol ref in the form \"<package>#<name>\", e.g. \"@dxos/echo#Expando\".',\n }),\n include: Schema.optional(Schema.Array(IncludeEnum)).annotations({\n title: 'Include',\n description: 'Optional fields to expand; default returns signature + summary only.',\n }),\n});\n\n//\n// Plugins / surfaces / capabilities / operations / schemas\n//\n// Main's API exposes a single optional `id` filter on each of these — the\n// plugin id (e.g. \"org.dxos.plugin.markdown\"). `listPlugins` accepts a\n// `PluginFilter` object with `id` for substring matching.\n//\n\nexport const ListPluginsInput = Schema.Struct({\n id: Schema.optional(Schema.String).annotations({\n title: 'Plugin id',\n description: 'Substring of the plugin id (case-insensitive). Omit to list every plugin.',\n }),\n ...ListOptionsInput.fields,\n});\n\nconst PluginIdFilter = Schema.Struct({\n id: Schema.optional(Schema.String).annotations({\n title: 'Plugin id',\n description: 'Restrict to contributions from this plugin id (e.g. \"org.dxos.plugin.markdown\").',\n }),\n ...ListOptionsInput.fields,\n});\n\nexport const ListSurfacesInput = PluginIdFilter;\nexport const ListCapabilitiesInput = PluginIdFilter;\nexport const ListOperationsInput = PluginIdFilter;\nexport const ListSchemasInput = PluginIdFilter;\n\n//\n// Inferred TypeScript types — handy for downstream consumers.\n//\n\nexport type ListPackagesArgs = typeof ListPackagesInput.Type;\nexport type GetPackageArgs = typeof GetPackageInput.Type;\nexport type ListSymbolsArgs = typeof ListSymbolsInput.Type;\nexport type FindSymbolArgs = typeof FindSymbolInput.Type;\nexport type GetSymbolArgs = typeof GetSymbolInput.Type;\nexport type ListPluginsArgs = typeof ListPluginsInput.Type;\nexport type ListSurfacesArgs = typeof ListSurfacesInput.Type;\nexport type ListCapabilitiesArgs = typeof ListCapabilitiesInput.Type;\nexport type ListOperationsArgs = typeof ListOperationsInput.Type;\nexport type ListSchemasArgs = typeof ListSchemasInput.Type;\n"],
5
+ "mappings": "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",
6
+ "names": ["DEFAULT_LIST_LIMIT", "MAX_LIST_LIMIT", "effectFieldsToZod", "trim", "Schema", "trim", "ListOptionsInput", "Struct", "limit", "optional", "Number", "pipe", "int", "positive", "lessThanOrEqualTo", "MAX_LIST_LIMIT", "annotations", "title", "description", "trim", "DEFAULT_LIST_LIMIT", "compact", "Boolean", "SymbolKindEnum", "Literal", "IncludeEnum", "ListPackagesInput", "name", "String", "pathPrefix", "privateOnly", "fields", "GetPackageInput", "ListSymbolsInput", "package", "kind", "FindSymbolInput", "query", "GetSymbolInput", "ref", "include", "Array", "ListPluginsInput", "id", "PluginIdFilter", "ListSurfacesInput", "ListCapabilitiesInput", "ListOperationsInput", "ListSchemasInput", "TOOL_METADATA", "list_packages", "title", "description", "trim", "inputSchema", "ListPackagesInput", "get_package", "GetPackageInput", "list_symbols", "ListSymbolsInput", "find_symbol", "FindSymbolInput", "get_symbol", "GetSymbolInput", "list_plugins", "ListPluginsInput", "list_surfaces", "ListSurfacesInput", "list_capabilities", "ListCapabilitiesInput", "list_operations", "ListOperationsInput", "list_schemas", "ListSchemasInput", "inputSchemaToZod", "struct", "effectFieldsToZod"]
7
+ }
@@ -0,0 +1 @@
1
+ {"inputs":{"src/limits.ts":{"bytes":3000,"imports":[],"format":"esm"},"src/schemas.ts":{"bytes":16540,"imports":[{"path":"effect/Schema","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"src/limits.ts","kind":"import-statement","original":"./limits"}],"format":"esm"},"src/metadata.ts":{"bytes":17520,"imports":[{"path":"@dxos/effect-zod","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"src/schemas.ts","kind":"import-statement","original":"./schemas"}],"format":"esm"},"src/index.ts":{"bytes":2842,"imports":[{"path":"src/limits.ts","kind":"import-statement","original":"./limits"},{"path":"src/metadata.ts","kind":"import-statement","original":"./metadata"},{"path":"src/schemas.ts","kind":"import-statement","original":"./schemas"}],"format":"esm"}},"outputs":{"dist/lib/node-esm/index.mjs.map":{"imports":[],"exports":[],"inputs":{},"bytes":17625},"dist/lib/node-esm/index.mjs":{"imports":[{"path":"@dxos/effect-zod","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true},{"path":"effect/Schema","kind":"import-statement","external":true},{"path":"@dxos/util","kind":"import-statement","external":true}],"exports":["DEFAULT_LIST_LIMIT","FindSymbolInput","GetPackageInput","GetSymbolInput","ListCapabilitiesInput","ListOperationsInput","ListOptionsInput","ListPackagesInput","ListPluginsInput","ListSchemasInput","ListSurfacesInput","ListSymbolsInput","MAX_LIST_LIMIT","TOOL_METADATA","inputSchemaToZod"],"entryPoint":"src/index.ts","inputs":{"src/limits.ts":{"bytesInOutput":55},"src/index.ts":{"bytesInOutput":0},"src/metadata.ts":{"bytesInOutput":4372},"src/schemas.ts":{"bytesInOutput":3311}},"bytes":8256}}}
@@ -0,0 +1,4 @@
1
+ export { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, type ListOptions } from './limits';
2
+ export { TOOL_METADATA, inputSchemaToZod, type ToolMetadata } from './metadata';
3
+ export { FindSymbolInput, GetPackageInput, GetSymbolInput, ListCapabilitiesInput, ListOperationsInput, ListOptionsInput, ListPackagesInput, ListPluginsInput, ListSchemasInput, ListSurfacesInput, ListSymbolsInput, type FindSymbolArgs, type GetPackageArgs, type GetSymbolArgs, type ListCapabilitiesArgs, type ListOperationsArgs, type ListPackagesArgs, type ListPluginsArgs, type ListSchemasArgs, type ListSurfacesArgs, type ListSymbolsArgs, } from './schemas';
4
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EACL,eAAe,EACf,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,WAAW,CAAC"}
@@ -0,0 +1,23 @@
1
+ /** Default number of items returned by list-style tools when no `limit` is passed. */
2
+ export declare const DEFAULT_LIST_LIMIT = 30;
3
+ /**
4
+ * Hard ceiling on `limit`. A runaway tool call shouldn't be able to dump every
5
+ * symbol in the monorepo (~thousands) into the model's context. Callers who
6
+ * truly need everything should iterate via filters (pluginId, package, etc.).
7
+ */
8
+ export declare const MAX_LIST_LIMIT = 200;
9
+ /**
10
+ * Per-call options every list-style tool accepts. Both fields are optional
11
+ * — the defaults match `DEFAULT_LIST_LIMIT` items, full projection.
12
+ */
13
+ export type ListOptions = {
14
+ /** Override the default `DEFAULT_LIST_LIMIT`. Capped at `MAX_LIST_LIMIT`. */
15
+ limit?: number;
16
+ /**
17
+ * Return only the most-essential identifying fields (ref/id/name) instead
18
+ * of the full record. Use when discovering what exists before drilling in
19
+ * with a `get_*` call. Roughly 1/4 the token cost.
20
+ */
21
+ compact?: boolean;
22
+ };
23
+ //# sourceMappingURL=limits.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../../src/limits.ts"],"names":[],"mappings":"AAUA,sFAAsF;AACtF,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC"}
@@ -0,0 +1,41 @@
1
+ import * as Schema from 'effect/Schema';
2
+ import type { z } from 'zod';
3
+ /**
4
+ * Pure metadata for a single MCP tool — what an MCP client needs to know
5
+ * before invoking it: human-readable title, an LLM-targeted description,
6
+ * and the Effect Schema input contract.
7
+ */
8
+ export type ToolMetadata = {
9
+ /** Human-readable title surfaced by Inspector / Composer. */
10
+ title: string;
11
+ /**
12
+ * LLM-targeted description. Models read this to decide WHEN to call the
13
+ * tool — write it for trigger accuracy, not for human reading. State both
14
+ * what the tool does and the situations it's the right answer for.
15
+ */
16
+ description: string;
17
+ /**
18
+ * Effect Schema struct describing the tool's input. Server-side, the
19
+ * MCP SDK requires zod, so the server converts to zod via
20
+ * `inputSchemaToZod` at registration time. Browser consumers
21
+ * (react-ui-form, etc.) use this directly.
22
+ */
23
+ inputSchema: Schema.Struct<any>;
24
+ };
25
+ /**
26
+ * Static metadata for every tool the introspect-mcp server exposes. No
27
+ * introspector or runtime state — safe to import from a browser bundle.
28
+ *
29
+ * Adding a tool means: (1) define its input schema in `./schemas.ts`,
30
+ * (2) add an entry here, (3) add a matching handler in
31
+ * `@dxos/introspect-mcp` that closes over a runtime `Introspector`.
32
+ */
33
+ export declare const TOOL_METADATA: Record<string, ToolMetadata>;
34
+ /**
35
+ * Materialize a tool's `inputSchema` (Effect Struct) into the
36
+ * `Record<string, z.ZodTypeAny>` shape the MCP SDK's `registerTool` requires.
37
+ * Called once per tool at server startup; throws with a clear message if a
38
+ * tool's input uses a schema pattern the converter doesn't support.
39
+ */
40
+ export declare const inputSchemaToZod: (struct: Schema.Struct<any>) => Record<string, z.ZodTypeAny>;
41
+ //# sourceMappingURL=metadata.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../../src/metadata.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkB7B;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;CACjC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CA4FtD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,WAAY,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAA8B,CAAC"}