@hediet/linkrpc-mcp 0.0.1

package/README.md

@@ -0,0 +1,82 @@
+# @hediet/linkrpc-mcp
+
+Stdio MCP server that lets an LLM drive a [linkrpc](../linkrpc) hub.
+
+## Tools
+
+### `runLinkRpcScript`
+
+Evaluates a JS function inside a [QuickJS](https://github.com/justjake/quickjs-emscripten) sandbox (~5 s CPU, ~32 MB memory) with these globals in scope:
+
+| Name                     | Description                                                                                                                                                                                         |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `con`                    | Live hub connection — see the `connection.d.ts` resource for the full signature. Covers `con.call`, `con.notify`, `con.callRaw`, `con.notifyRaw`, **and `con.explore(...)`** for service discovery. |
+| `lastResultVal`          | The previous `runLinkRpcScript` result against the same hub. JSON round-tripped. `undefined` on the first call.                                                                                      |
+| `mcp`                    | Optional result-presentation helpers: `raw`, `text`, `image`, `audio`, `resource`, `resourceLink`, `content`, and `result`.                                                                         |
+| `console.log/warn/error` | Captured and returned alongside the result.                                                                                                                                                         |
+
+`code` must evaluate to a function:
+
+```js
+({ con }) => con.call("vscode", "vscode.window",
+                      "showInformationMessage",
+                      { message: "hello world" })
+```
+
+Set `connection` to a hub endpoint URI (e.g. `unix:/path?token=…`, `npipe://./pipe/…?token=…`, or `wss://host?token=…`) to target a specific hub, or omit it to use the `LINKRPC_ENDPOINT` / `LINKRPC_TOKEN` env vars (set by the team-tools extension on every terminal). The token may be embedded in the URI or supplied via `LINKRPC_TOKEN`.
+
+#### Result presentation
+
+Return values remain unchanged while the script runs, when passed to another hub
+service, and when stored in `lastResultVal`. At the final MCP boundary, the server
+automatically recognizes:
+
+- MCP text, image, audio, embedded-resource, and resource-link blocks;
+- `data:` URLs;
+- common image/audio/document base64 signatures;
+- `{ data|base64|blob, mimeType }` and `{ text, mimeType }` objects.
+
+Recognized values become native MCP content blocks. Their base64 is replaced in the
+JSON text and `structuredContent` fallbacks by a small descriptor. Set
+`presentation: "raw"` on `runLinkRpcScript`, `awaitLinkRpcTask`, or
+`cancelLinkRpcTask` to expose the original JSON, or selectively return
+`mcp.raw(value)`.
+
+Explicit content needs little ceremony:
+
+```js
+({ mcp }) => mcp.result({
+    value: { width: 800, height: 600 },
+    content: [
+        mcp.image(pngBase64, "image/png"),
+        mcp.resourceLink({
+            uri: "file:///report.pdf",
+            name: "report.pdf",
+            mimeType: "application/pdf",
+        }),
+    ],
+})
+```
+
+The `mcp.*` values are presentation markers intended to be returned from the
+script. Keep using the original value for intermediate hub calls.
+
+## Resources
+
+### `linkrpc-mcp://docs/connection.d.ts`
+
+TypeScript declarations for the in-sandbox API (`con`, `console`, `lastResultVal`). Read this once before authoring `runLinkRpcScript` calls.
+
+## Running locally
+
+```jsonc
+// .vscode/mcp.json
+{
+    "servers": {
+        "linkrpc": {
+            "command": "npx",
+            "args": ["@hediet/linkrpc-mcp"]
+        }
+    }
+}
+```

package/dist/chunks/server-Bquqk9Mk.d.ts

@@ -0,0 +1,248 @@
+import { IMessageTransport, IRequestSender, SignedCapability, SigningCallCtx } from "@hediet/linkrpc";
+import { ResolvedEndpoint } from "@hediet/linkrpc/node";
+import { HubAccessRequest, HubAccessResult } from "@hediet/linkrpc/hub/common";
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { HubSigningSender } from "@hediet/linkrpc/hub/client";
+//#region src/connectionPool.d.ts
+/** Receives one trace line at a time. */
+type TraceListener = (line: string) => void;
+/**
+ * Minimal hub-access surface the MCP tools consume from a connection: read the
+ * current grants and request more. Satisfied by both a CLI {@link SigningSession}
+ * (endpoint pool) and a {@link import('@hediet/linkrpc/hub/client').HubSigningSender}
+ * (consumer-provided sender).
+ */
+interface HubAccess {
+  listGrants(): readonly SignedCapability[];
+  requestAccess(req: HubAccessRequest): Promise<HubAccessResult>;
+}
+/**
+ * One MCP-server-wide live linkrpc connection. We keep a single connection per
+ * unique endpoint URI (path/url + token) so repeated tool calls reuse the same
+ * socket and the per-connection `lastResultVal` survives across runs.
+ */
+interface PooledConnection {
+  readonly channel: IRequestSender<SigningCallCtx>;
+  /** Redacted endpoint URI of this connection, for labels and tool results. */
+  readonly endpoint: string;
+  /**
+   * Canonical endpoint URI (token revealed) — uniquely identifies this
+   * connection. Used to key per-connection background tasks so that a new
+   * request on the same connection supersedes the previous task.
+   */
+  readonly key: string;
+  /**
+   * Hub signing session: signs every outbound call with the connection's
+   * identity and exposes the grant surface ({@link HubAccess}). For the
+   * endpoint pool this is a CLI `SigningSession`; for a consumer-provided
+   * sender it is the sender itself.
+   */
+  readonly session: HubAccess;
+  /** Most recent value returned by `runLinkRpcScript`. Updated after each run. */
+  lastResultVal: unknown;
+  /**
+   * Subscribe `listener` to every JSON-RPC trace line produced while
+   * the subscription is live (in addition to the always-on stderr
+   * mirror). Returns a disposer that removes the listener. Multiple
+   * concurrent listeners are supported — each sees every line —
+   * which means concurrent runs on the same pooled connection will
+   * see each other's traces. That matches the channel's own
+   * concurrency model.
+   */
+  addTraceListener(listener: TraceListener): () => void;
+  /** Emit a trace line on this connection (also writes to stderr). */
+  trace(line: string): void;
+  /** Close the underlying socket and drop the entry from the pool. */
+  dispose(): void;
+}
+/**
+ * Subset of {@link ConnectionPool} used by the MCP server, extracted so tests
+ * can inject a fake pool without standing up a real hub connection.
+ */
+interface IConnectionPool {
+  resolve(endpointUri: string | undefined): Promise<PooledConnection>;
+  dispose(): void;
+}
+/** Plain JSON-RPC connection descriptor sent by the MCP client. */
+interface ConnectionPoolOptions {
+  /**
+   * Endpoint used when a tool call does not specify a `connection`. When
+   * neither the caller nor a default is supplied, the pool falls back to the
+   * `LINKRPC_ENDPOINT` / `LINKRPC_TOKEN` environment variables.
+   */
+  readonly defaultEndpoint?: ResolvedEndpoint;
+  /**
+   * Opens the **default** connection (the one used when a tool call supplies
+   * no `connection` argument) over an in-process transport instead of dialing
+   * a socket — typically a leg into an in-process hub participant. When set it
+   * takes precedence over {@link defaultEndpoint} / env vars for the
+   * no-argument case; explicit `connection` endpoint URIs still dial normally.
+   *
+   * Called lazily on first use; the returned {@link DefaultTransport.dispose}
+   * runs when the pooled connection is disposed.
+   */
+  readonly defaultTransport?: () => DefaultTransport;
+}
+/**
+ * An in-process transport supplying the pool's default connection, plus
+ * presentation/teardown hooks. The pool wraps {@link transport} in a managed
+ * signing connection ({@link connectViaTransport} + `setupSigning`), exactly as
+ * it would a dialed socket.
+ */
+interface DefaultTransport {
+  /** In-memory transport whose peer serves the hub (incl. `identity::*`). */
+  readonly transport: IMessageTransport;
+  /** Human-readable label for traces / tool results. Defaults to `"inproc"`. */
+  readonly label?: string;
+  /** Extra teardown run when the pooled connection is disposed (after `cli.close`). */
+  readonly dispose?: () => void;
+}
+/**
+ * Maintains live hub connections keyed by the canonical endpoint URI (path/url
+ * + token). Connections are created lazily on first use and reused for every
+ * subsequent call against the same endpoint. Setting up the hub signing session
+ * (which may surface a consent modal the first time) happens once per endpoint
+ * and the resulting session is cached on the pool entry.
+ */
+declare class ConnectionPool implements IConnectionPool {
+  private readonly _entries;
+  private readonly _defaultEndpoint;
+  private readonly _defaultTransport;
+  /** Pool key for the in-process default connection (see {@link ConnectionPoolOptions.defaultTransport}). */
+  private static readonly _DEFAULT_INPROC_KEY;
+  constructor(options?: ConnectionPoolOptions);
+  /**
+   * Resolve a pooled connection for `endpointUri` (a strict endpoint URI such
+   * as `unix:/path?token=…`, `npipe://./pipe/…?token=…`, or
+   * `wss://host?token=…`). When omitted, an in-process default transport (if
+   * configured) is used; otherwise it falls back to the configured default
+   * endpoint, then to the `LINKRPC_ENDPOINT` / `LINKRPC_TOKEN` env vars. A token
+   * absent from the URI is filled in from `LINKRPC_TOKEN` when present.
+   */
+  resolve(endpointUri: string | undefined): Promise<PooledConnection>;
+  /**
+   * Shared cache-or-open: returns the in-flight/cached entry for `key`, or
+   * starts `open(key)` and caches the promise so concurrent callers share the
+   * same signing setup. On failure the entry is evicted so the next call
+   * retries cleanly.
+   */
+  private _resolveCached;
+  private _resolveSpec;
+  private _open;
+  private _openInProc;
+  /**
+   * Wrap an already-open {@link CliConnection} in a managed signing session
+   * and build the {@link PooledConnection}. Shared by the dialed-socket and
+   * in-process default paths — both sign as a managed principal and bootstrap
+   * the `hubAccess` cap, the only difference being how the transport was
+   * obtained. `extraDispose` runs on disposal after the connection is closed.
+   */
+  private _finishOpen;
+  dispose(): void;
+}
+//#endregion
+//#region src/senderProvider.d.ts
+/** Identifies the MCP session a connection is opened for (consumer-provided mode). */
+interface McpSessionInfo {
+  readonly sessionId?: string;
+  readonly authorization?: string;
+}
+/**
+ * Resolves a {@link HubSigningSender} for an MCP session and an optional
+ * `connection` endpoint argument (`undefined` → the provider's default). This is
+ * the single injection seam for both identity-provision modes:
+ *   - package-provisioned: the provider dials an endpoint and signs (managed).
+ *   - consumer-provisioned: the embedder returns a sender bound to a per-session
+ *     identity it owns (e.g. an in-process hub participant).
+ */
+type HubSenderProvider = (session: McpSessionInfo | undefined, endpoint: string | undefined) => Promise<HubSigningSender>;
+/**
+ * {@link IConnectionPool} backed by a {@link HubSenderProvider}: caches one
+ * {@link HubSigningSender} per distinct `connection` argument and adapts it to
+ * the {@link PooledConnection} shape the MCP tools consume. Holds the
+ * MCP-layer-only `lastResultVal` and trace fan-out so the sender stays pure.
+ */
+declare class ProviderPool implements IConnectionPool {
+  private readonly _provider;
+  private readonly _session?;
+  private readonly _entries;
+  constructor(_provider: HubSenderProvider, _session?: McpSessionInfo | undefined);
+  resolve(endpointUri: string | undefined): Promise<PooledConnection>;
+  private _open;
+  dispose(): void;
+}
+//#endregion
+//#region src/server.d.ts
+interface McpToolCall {
+  readonly name: string;
+  readonly arguments: unknown;
+  readonly result: unknown;
+}
+type McpExploreCall = {
+  readonly arguments: unknown;
+  readonly result: unknown;
+} | {
+  readonly arguments: unknown;
+  readonly error: string;
+};
+interface LinkRpcMcpServerOptions {
+  /**
+   * Endpoint used when the tool call does not supply a `connection`. When
+   * omitted, the server falls back to the `LINKRPC_ENDPOINT` / `LINKRPC_TOKEN`
+   * environment variables (the stdio CLI mode).
+   */
+  readonly defaultEndpoint?: ResolvedEndpoint;
+  /**
+   * Connection pool to use. Defaults to a real {@link ConnectionPool}.
+   * Injectable so tests can supply a fake pool without a live hub.
+   */
+  readonly pool?: IConnectionPool;
+  /**
+   * Resolves a signing sender per MCP session / `connection` argument instead
+   * of dialing an endpoint. When set (and no explicit `pool` is given), the
+   * server uses a {@link ProviderPool} — the consumer-provisioned identity
+   * mode. Mutually exclusive with `defaultEndpoint`.
+   */
+  readonly provider?: HubSenderProvider;
+  /**
+   * Supplies the **default** connection (used when a tool call omits
+   * `connection`) over an in-process transport — typically a leg into an
+   * in-process hub participant — instead of dialing a socket. Explicit
+   * `connection` endpoint URIs still dial normally. Combine with
+   * {@link defaultEndpoint} to additionally set a dialed fallback; mutually
+   * exclusive with `pool` / `provider`.
+   */
+  readonly defaultConnection?: () => DefaultTransport;
+  /** Observes completed MCP tool calls exactly as their result is returned to the client. */
+  readonly onToolCall?: (call: McpToolCall) => void;
+  /** Observes every sandbox `con.explore` call, including calls that fail. */
+  readonly onExploreCall?: (call: McpExploreCall) => void;
+}
+/**
+ * MCP server exposing the `runLinkRpcScript` tool plus task-management helpers.
+ *
+ * Documentation for the sandbox API (`con`) is reachable from inside the
+ * sandbox via `con.getDocs()` rather than an MCP resource — that way the
+ * model can pull it in by issuing a one-line `runLinkRpcScript` call.
+ *
+ * Can be hosted over stdio (CLI mode, via {@link startStdio}) or over any
+ * MCP {@link Transport} (e.g. Streamable HTTP, used by the VS Code Team
+ * Tools extension which embeds this server in-process).
+ */
+declare class LinkRpcMcpServer {
+  static startStdio(options?: LinkRpcMcpServerOptions): Promise<LinkRpcMcpServer>;
+  private readonly _mcp;
+  private readonly _pool;
+  private readonly _tasks;
+  private readonly _onToolCall;
+  private readonly _onExploreCall;
+  constructor(options?: LinkRpcMcpServerOptions);
+  connect(transport: Transport): Promise<void>;
+  dispose(): void;
+  private _registerTools;
+  private _observeToolCall;
+  private _observeExploreCall;
+}
+//#endregion
+export { HubSenderProvider as a, ConnectionPool as c, HubAccess as d, IConnectionPool as f, McpToolCall as i, ConnectionPoolOptions as l, TraceListener as m, LinkRpcMcpServerOptions as n, McpSessionInfo as o, PooledConnection as p, McpExploreCall as r, ProviderPool as s, LinkRpcMcpServer as t, DefaultTransport as u };
+//# sourceMappingURL=server-Bquqk9Mk.d.ts.map