@qodo/sdk 0.13.4 → 2.0.0-next.0

package/dist/skills/mcp/server.d.ts

@@ -0,0 +1,144 @@
+/**
+ * `qodo-skills` MCP server implementation.
+ *
+ * Three tools, all `autoApproved: true`: `list_skills`, `get_skill`,
+ * `get_skill_file`. The server is a thin facade over a `SkillsManager`
+ * — the heavy lifting (catalog walk, parsing, validation, rendering) lives
+ * in the manager. The server owns:
+ *
+ *   - Tool-routing (which handler runs for which `tool_name`).
+ *   - In-memory caches keyed by `<fqn>` + `<fqn> + <rel-path>`.
+ *   - Path validation for `get_skill_file` (see `path.ts`).
+ *   - Telemetry emission via the manager's `forwardEvents` sink.
+ *   - Structured error responses on the `isError: true` envelope.
+ *
+ * Integration: the SDK has no `InternalMCPBaseServer` interface. The
+ * integration shape is `McpInProcessHandler` from `QarRegistryClient`
+ * (`(req: { tool_name, arguments }) => Promise<...>`); the
+ * `QodoSkillsMcpServer` class is invoked via the {@link asMcpHandler}
+ * adapter. The SDK ships zero built-in MCPs by default — this server
+ * auto-registers via `client.qar.registerMcp('qodo-skills',
+ * { transport: 'sdk', handler })` when `ClientOptions.skills` is
+ * provided. Reach the registered config via
+ * `client.qar.getMcp('qodo-skills')`; the server instance itself is
+ * owned by `QodoClient`.
+ *
+ * Caches are cleared on {@link QodoSkillsMcpServer.dispose}.
+ */
+import type { McpInProcessHandler } from '../../client/QarRegistryClient.js';
+import type { SkillsManager } from '../manager.js';
+import type { SubstitutionContext } from '../substitute.js';
+import type { McpToolResult, QodoSkillsMcpEvent } from './types.js';
+/** The MCP tool names the server routes. */
+export declare const QODO_SKILLS_TOOL_NAMES: readonly ["list_skills", "get_skill", "get_skill_file"];
+export type QodoSkillsToolName = (typeof QODO_SKILLS_TOOL_NAMES)[number];
+export { qodoSkillsFunctionToolDefs } from './wireDefs.js';
+/**
+ * Server class for the three `qodo-skills` MCP tools. Construct one per
+ * `QodoClient` instance; the SDK auto-wires it through
+ * {@link QodoClient.constructor} when `ClientOptions.skills` is configured.
+ */
+export declare class QodoSkillsMcpServer {
+    private readonly skills;
+    private readonly bodyCache;
+    private readonly fileCache;
+    /**
+     * Shared with `SkillsManager.internalActiveFqns` so caller-pin
+     * activation and LLM-driven activation surface in one place
+     * (`client.skills.getActiveSkills()` /
+     * `client.skillsMcpServer.loadedSkillFqns`). The MCP server still owns
+     * the body / file caches it manages, but it does NOT own the active
+     * set — the manager does.
+     */
+    private readonly activeFqns;
+    private readonly emit;
+    /**
+     * Resolver for ambient substitution context. Wired in by `QodoClient` so
+     * each `get_skill` invocation sees the consumer's session ID, the active
+     * effort level, and the current `${QODO_SKILL_DIR}` (= the skill's own
+     * canonical path). When undefined, those envvar substitutions stay literal.
+     */
+    private readonly resolveContext;
+    constructor(skills: SkillsManager, opts?: {
+        readonly emit?: (event: QodoSkillsMcpEvent) => void;
+        /**
+         * Lazy resolver for runtime context (session ID, effort). Re-evaluated
+         * on every `get_skill` call so a long-lived MCP server tracks the
+         * active task's identity.
+         */
+        readonly resolveContext?: () => Partial<SubstitutionContext>;
+    });
+    /**
+     * The set of skill FQNs whose body has been loaded into the current run.
+     * Surfaces for testing + for forward-looking trust-tier middleware that
+     * needs to know which skills' `allowed-tools` should be in scope.
+     */
+    get loadedSkillFqns(): readonly string[];
+    /** Bytes currently held in the body cache. Useful for memory-pressure tests. */
+    get cachedBodyBytes(): number;
+    /**
+     * Drop the in-memory caches and active-skill set. Idempotent. Called by
+     * `QodoClient.disconnect()` so the next `connect()` starts cold.
+     *
+     * The active set is shared with `SkillsManager.internalActiveFqns`;
+     * clearing here implicitly clears the manager's surface too — both
+     * `client.skills.getActiveSkills()` and `client.skillsMcpServer.loadedSkillFqns`
+     * return empty after dispose.
+     */
+    dispose(): void;
+    /**
+     * Route a call by `tool_name` to the matching handler. Unknown names
+     * return an MCP error envelope. The handler signature matches the
+     * `McpInProcessHandler` contract so the same instance is registered via
+     * `client.qar.registerMcp(name, { transport: 'sdk', handler })`.
+     */
+    callTool(toolName: string, args: Record<string, unknown>): Promise<McpToolResult>;
+    private handleListSkills;
+    private handleGetSkill;
+    /**
+     * Convert an activation-resolver failure into the matching telemetry
+     * event(s). Cycles + unresolved-dep failures piggyback on the existing
+     * `sdk.skill.error` channel; trust violations and cap breaches have
+     * dedicated event kinds.
+     */
+    private emitResolverFailure;
+    /**
+     * Emit the `allowed-tools` telemetry shape (`applied` for trusted,
+     * `advisory` for third-party). Same logic as the SDK's caller-pin
+     * activation path; kept in sync intentionally.
+     */
+    private emitAllowedToolsEvents;
+    private handleGetSkillFile;
+    /**
+     * Render the file envelope, applying substitutions to markdown / text
+     * content. Cache hits go through the same path so substitutions apply
+     * even on cached reads.
+     */
+    private renderFileEnvelope;
+    /**
+     * Forward substitution warnings from `substitute(...)` through the
+     * manager's telemetry sink. Each `SubstitutionWarning` becomes one
+     * `sdk.skill.substitution_warn` event keyed to the skill that emitted it.
+     */
+    private emitSubstitutionWarnings;
+    /**
+     * Forward MCP-specific telemetry through the manager's sink. The base
+     * `SkillEvent` union doesn't include these MCP-only kinds; the
+     * manager's sink accepts a superset, so we cast through `unknown` at
+     * the boundary. Consumers reading `SkillEvent` discriminate by `kind`
+     * literal.
+     */
+    private emitTel;
+}
+/**
+ * Adapt a {@link QodoSkillsMcpServer} to the {@link McpInProcessHandler}
+ * shape expected by `client.qar.registerMcp('qodo-skills', { transport:
+ * 'sdk', handler })`. The handler unwraps the wire `{ tool_name, arguments }`
+ * shape and delegates to {@link QodoSkillsMcpServer.callTool}.
+ *
+ * The returned value is the MCP envelope `{ content, isError? }`. QAR's
+ * agent loop reads `content[0].text` (or `content[0].data` for images) as
+ * the tool call's response payload.
+ */
+export declare function asMcpHandler(server: QodoSkillsMcpServer): McpInProcessHandler;
+//# sourceMappingURL=server.d.ts.map

package/dist/skills/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/skills/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAG7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAUnD,OAAO,KAAK,EAAE,mBAAmB,EAAuB,MAAM,kBAAkB,CAAC;AACjF,OAAO,KAAK,EAMV,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAiEpB,4CAA4C;AAC5C,eAAO,MAAM,sBAAsB,yDAA0D,CAAC;AAC9F,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAKzE,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAkB3D;;;;GAIG;AACH,qBAAa,mBAAmB;IAuB5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAtBzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAC3D;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAc;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoD;IAEzE;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAmD;gBAG/D,MAAM,EAAE,aAAa,EACtC,IAAI,CAAC,EAAE;QACL,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;QACpD;;;;WAIG;QACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;KAC9D;IAOH;;;;OAIG;IACH,IAAW,eAAe,IAAI,SAAS,MAAM,EAAE,CAE9C;IAED,gFAAgF;IAChF,IAAW,eAAe,IAAI,MAAM,CAInC;IAED;;;;;;;;OAQG;IACI,OAAO,IAAI,IAAI;IAMtB;;;;;OAKG;IACU,QAAQ,CACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,aAAa,CAAC;YAiBX,gBAAgB;YA8BhB,cAAc;IAmK5B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IA+C3B;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;YAehB,kBAAkB;IA0JhC;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAwB1B;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAehC;;;;;;OAMG;IACH,OAAO,CAAC,OAAO;CAahB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAK7E"}