@glyphp/adapter-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,67 @@
+# @glyphp/adapter-mcp-server
+
+> Expose a [Glyph Protocol](https://github.com/Monoperro0207/glyph-protocol) server's tools to any [Model Context Protocol](https://modelcontextprotocol.io) client (Claude Desktop, Hermes Agent, Cursor, etc.).
+
+This is the **inverse direction** of `@glyphp/adapter-mcp` (which adapts MCP tools *into* Glyph). Together they let the two ecosystems consume each other.
+
+## Install
+
+```bash
+pnpm add @glyphp/adapter-mcp-server @glyphp/client
+```
+
+## Use
+
+```ts
+import { GlyphClient } from '@glyphp/client'
+import { runStdioBridge } from '@glyphp/adapter-mcp-server'
+
+const client = new GlyphClient({ baseUrl: 'http://localhost:3199' })
+await runStdioBridge(client) // MCP stdio server now serving Glyph tools
+```
+
+Point any MCP client at the resulting process — `claude_desktop_config.json`, Hermes Agent's `mcp_servers` block, Cursor's MCP setting — and the Glyph server's tools appear as native MCP tools.
+
+## Two modes: eager vs lazy
+
+The example above uses **eager mode** — every Glyph card is surfaced as its own MCP tool. Simple, works with any MCP client, but every `tools/list` carries every schema.
+
+For large catalogs (dozens of tools), use **lazy mode**. It exposes only three meta-tools — `glyph_index`, `glyph_describe`, `glyph_invoke` — and lets the model navigate on demand. Cards the agent never touches never enter context.
+
+```ts
+import { runStdioBridgeLazy } from '@glyphp/adapter-mcp-server'
+await runStdioBridgeLazy(client)
+```
+
+Measured trade-off (`spec/tests/hermes-comparative-deepseek.md` — same prompt, same 49 tools, `deepseek-v4-pro`):
+
+| Metric | Eager | Lazy | Δ |
+|---:|---:|---:|---:|
+| Tools visible in `tools/list` | 49 | 3 | — |
+| Listing tokens (per turn) | 4,129 | 256 | **−93.8%** |
+| Total tokens (full task) | 168,971 | 77,576 | **−54.1%** |
+| Cost (DeepSeek rates) | $0.0227 | $0.0137 | −40% |
+
+The honest catch: lazy mode pays two extra round-trips at the start of a session for discovery. For very small catalogs (<10 tools) or one-shot tasks, eager is preferable. The two modes are exported side-by-side — pick the right one for your shape of problem.
+
+## Honest mapping
+
+MCP and Glyph are not isomorphic. The bridge preserves what MCP can carry and consumes the rest server-side:
+
+| Glyph concept | What the bridge does |
+|---|---|
+| `card.name` | Becomes the MCP tool name |
+| `card.intent` | Becomes the MCP tool description |
+| `card.cost.riskTier` / `sideEffects` / `reversible` | Surfaced **in the description** so the model can reason about blast radius before invoking |
+| `card.input` schema | Passed through verbatim as MCP `inputSchema` |
+| `card.publicKey` / `signature` | Verified by `GlyphClient` server-side — **not exposed to MCP** (MCP has nowhere to put them) |
+| `cost.requiresConfirmation: true` | Refused at the bridge with a clear error — the MCP transport has no ticket/confirmation flow, and auto-confirming would defeat the gate |
+| `SealedEnvelope.receipt` | Verified server-side, then **dropped** — MCP has no signed-receipt concept |
+| `SealedEnvelope.inspection` | When sanitization removed content, a short annotation is appended to the MCP response text so the consuming model knows defense ran |
+| `card.attestation` | **Not exposed.** A consumer that needs to verify attestations should speak Glyph natively |
+
+If your use case requires the cryptographic guarantees (signed receipts for audit, attestation verification, pinning gates), use `@glyphp/client` directly. The bridge is for **integration with the MCP ecosystem**, not for security-critical paths.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GlyphClient } from '@glyphp/client';
+export interface BridgeOptions {
+    /** Reported as the MCP server name on handshake. */
+    serverName?: string;
+    /** Reported as the MCP server version on handshake. */
+    serverVersion?: string;
+    /**
+     * When false, the bridge fetches the lexicon on every `tools/list` call.
+     * When true (default), it caches per session for speed. Cache lives for
+     * the lifetime of the bridge process; restart to pick up new tools.
+     */
+    cacheLexicon?: boolean;
+}
+/**
+ * Builds an MCP Server that exposes a Glyph server's tools. Wire it up with
+ * any transport — stdio is most common.
+ *
+ * @example
+ *   const client = new GlyphClient({ baseUrl: 'http://localhost:3199' })
+ *   const server = mcpServerFromGlyph(client)
+ *   await server.connect(new StdioServerTransport())
+ */
+export declare function mcpServerFromGlyph(client: GlyphClient, options?: BridgeOptions): Server;
+/**
+ * Convenience: builds the bridge and connects it over stdio. Useful for a
+ * one-line bin script. Resolves once the transport is wired.
+ */
+export declare function runStdioBridge(client: GlyphClient, options?: BridgeOptions): Promise<Server>;
+export { mcpServerFromGlyphLazy, runStdioBridgeLazy, type LazyBridgeOptions, } from './lazy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwCA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAGjD,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CA8GR;AAyDD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,iBAAiB,GACvB,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1,206 @@
+/**
+ * @glyphp/adapter-mcp-server — expose a Glyph Protocol server's tools to any
+ * MCP client.
+ *
+ * Two modes:
+ *   - **Eager** (this file): every Glyph card surfaced as an MCP tool. Simple,
+ *     works with any MCP client, but every `tools/list` carries every schema.
+ *   - **Lazy** (`./lazy.ts`): only three meta-tools (`glyph_index`,
+ *     `glyph_describe`, `glyph_invoke`). The model navigates on demand.
+ *     Tokens spent on tool descriptions drop ~80-95% on multi-tool servers.
+ *
+ * This is the inverse direction of `@glyphp/adapter-mcp`. Together they let
+ * Glyph and MCP ecosystems consume each other.
+ *
+ * ## Honest mapping notes
+ *
+ * MCP and Glyph are not isomorphic. The bridge preserves what MCP can carry
+ * and consumes the rest server-side:
+ *
+ * - **Preserved**: tool name, intent (as description), input schema, output
+ *   payload, risk-tier as a description annotation.
+ * - **Surfaced as MCP isError**: confirmation gate refusals (when a Glyph
+ *   tool declares `requiresConfirmation`, the bridge cannot satisfy the
+ *   ticket flow for an MCP client that has no ticket concept — the call is
+ *   refused with a clear error).
+ * - **Consumed server-side**: card signatures (verified by GlyphClient),
+ *   receipt signatures (verified by GlyphClient), the SealedEnvelope's
+ *   `inspection` report — when it removed anything, a brief note is appended
+ *   to the MCP content so the calling model sees that sanitization happened.
+ * - **Lost**: the cryptographic receipt itself, the publicKey, the
+ *   attestation envelope. MCP has nowhere to put them. This is the
+ *   structural reason a security-conscious consumer should speak Glyph
+ *   natively rather than through this bridge.
+ *
+ * See `spec/tests/hermes-deepseek.md` for a worked example.
+ */
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+/**
+ * Builds an MCP Server that exposes a Glyph server's tools. Wire it up with
+ * any transport — stdio is most common.
+ *
+ * @example
+ *   const client = new GlyphClient({ baseUrl: 'http://localhost:3199' })
+ *   const server = mcpServerFromGlyph(client)
+ *   await server.connect(new StdioServerTransport())
+ */
+export function mcpServerFromGlyph(client, options = {}) {
+    const server = new Server({
+        name: options.serverName ?? 'glyph-mcp-bridge',
+        version: options.serverVersion ?? '0.1.0',
+    }, { capabilities: { tools: {} } });
+    /**
+     * MCP tool names match OpenAI's restriction: `^[a-zA-Z0-9_-]+$`. Glyph
+     * allows richer names (dots, slashes) — `fs.read`, `db/query`, etc. We
+     * translate by replacing every disallowed character with `_` and keep a
+     * reverse map so `tools/call` can find the original card. Collisions are
+     * caught at registration time (two glyph names that normalize to the same
+     * MCP name throw).
+     */
+    let cardCache;
+    /** mcp-safe-name → original card.name */
+    let nameAlias;
+    const sanitizeMcpName = (name) => name.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const loadCards = async () => {
+        if (cardCache && nameAlias && options.cacheLexicon !== false) {
+            return { cards: cardCache, alias: nameAlias };
+        }
+        const lexicon = await client.getLexicon();
+        const cards = new Map();
+        const alias = new Map();
+        for (const entry of lexicon) {
+            const card = await client.getCard(entry.name, 'rich');
+            cards.set(entry.name, card);
+            const safe = sanitizeMcpName(entry.name);
+            if (alias.has(safe)) {
+                throw new Error(`MCP name collision: glyph "${entry.name}" and "${alias.get(safe)}" both normalize to "${safe}". Rename one.`);
+            }
+            alias.set(safe, entry.name);
+        }
+        cardCache = cards;
+        nameAlias = alias;
+        return { cards, alias };
+    };
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const { cards } = await loadCards();
+        return {
+            tools: Array.from(cards.values()).map((card) => ({
+                name: sanitizeMcpName(card.name),
+                description: describeForMcp(card),
+                inputSchema: card.input ?? {
+                    type: 'object',
+                },
+            })),
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args } = req.params;
+        const { cards, alias } = await loadCards();
+        // Accept either the MCP-safe name (what the model saw) or the original
+        // glyph name. Most clients echo the listed name verbatim.
+        const originalName = alias.get(name) ?? name;
+        const card = cards.get(originalName);
+        if (!card) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Unknown Glyph tool: ${name}` }],
+            };
+        }
+        // Glyph's confirmation gate has no MCP equivalent. Refusing here surfaces
+        // the requirement to the model rather than silently approving — which
+        // would defeat the gate's purpose.
+        if (card.cost.requiresConfirmation) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Glyph tool "${name}" requires confirmation. The MCP bridge cannot satisfy this flow — call this tool via a native Glyph client that supports the prepare/confirm handshake.`,
+                    },
+                ],
+            };
+        }
+        try {
+            const envelope = (await client.call(originalName, (args ?? {})));
+            return envelopeToMcpResult(envelope);
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Glyph call failed: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+            };
+        }
+    });
+    return server;
+}
+/**
+ * Builds the MCP `description` string the model sees. We surface the risk
+ * tier and confirmation flag in plain language so the model can reason about
+ * blast radius before invoking — matching the spirit of MCP's annotations
+ * but with the explicit Glyph vocabulary preserved.
+ */
+function describeForMcp(card) {
+    const tags = [];
+    if (card.cost.riskTier !== 'safe') {
+        tags.push(`risk: ${card.cost.riskTier}`);
+    }
+    if (card.cost.sideEffects)
+        tags.push('has side effects');
+    if (!card.cost.reversible)
+        tags.push('not reversible');
+    if (card.cost.requiresConfirmation)
+        tags.push('requires confirmation');
+    const suffix = tags.length > 0 ? ` (${tags.join(', ')})` : '';
+    return `${card.intent}${suffix}`;
+}
+/**
+ * Maps a SealedEnvelope to an MCP CallToolResult. We:
+ *  - Encode the payload as a single text content block (JSON-stringified).
+ *  - If sanitization removed anything, append a brief annotation so the
+ *    model sees that Glyph defended against invisible content — this is the
+ *    only place the bridge surfaces the security work it did.
+ */
+function envelopeToMcpResult(envelope) {
+    const blocks = [
+        {
+            type: 'text',
+            text: typeof envelope.payload === 'string'
+                ? envelope.payload
+                : JSON.stringify(envelope.payload, null, 2),
+        },
+    ];
+    const inspection = envelope.inspection;
+    if (inspection && inspection.findings.length > 0) {
+        const counts = new Map();
+        for (const f of inspection.findings) {
+            counts.set(f.kind, (counts.get(f.kind) ?? 0) + f.count);
+        }
+        const breakdown = Array.from(counts.entries())
+            .map(([kind, count]) => `${count} ${kind}`)
+            .join(', ');
+        const total = Array.from(counts.values()).reduce((a, b) => a + b, 0);
+        blocks.push({
+            type: 'text',
+            text: `[glyph: sanitized ${total} invisible character(s) from this output — ${breakdown}]`,
+        });
+    }
+    return { content: blocks };
+}
+/**
+ * Convenience: builds the bridge and connects it over stdio. Useful for a
+ * one-line bin script. Resolves once the transport is wired.
+ */
+export async function runStdioBridge(client, options) {
+    const server = mcpServerFromGlyph(client, options);
+    await server.connect(new StdioServerTransport());
+    return server;
+}
+export { mcpServerFromGlyphLazy, runStdioBridgeLazy, } from './lazy.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lazy.d.ts

@@ -0,0 +1,9 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GlyphClient } from '@glyphp/client';
+export interface LazyBridgeOptions {
+    serverName?: string;
+    serverVersion?: string;
+}
+export declare function mcpServerFromGlyphLazy(client: GlyphClient, options?: LazyBridgeOptions): Server;
+export declare function runStdioBridgeLazy(client: GlyphClient, options?: LazyBridgeOptions): Promise<Server>;
+//# sourceMappingURL=lazy.d.ts.map

package/dist/lazy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy.d.ts","sourceRoot":"","sources":["../src/lazy.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAGjD,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAkCD,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CA6FR;AAuCD,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAIjB"}

package/dist/lazy.js

@@ -0,0 +1,168 @@
+/**
+ * Lazy bridge mode — Glyph's actual cost-saving philosophy.
+ *
+ * Where the eager bridge (in `index.ts`) dumps every card's schema into
+ * `tools/list` (so a 50-tool server costs ~12k tokens per turn), the lazy
+ * bridge exposes **only three meta-tools** to MCP:
+ *
+ *   1. `glyph_index`   → cheap directory: [{name, oneLineIntent, riskTier}]
+ *   2. `glyph_describe` → full card for a single tool (schema, cost, etc.)
+ *   3. `glyph_invoke`  → run the underlying glyph
+ *
+ * The model navigates: list cheap → describe what it needs → invoke. Cards
+ * the agent never touches never enter context. For a 50-tool server on a
+ * 10-turn task that touches ~6 tools, this is typically an 80-95% reduction
+ * in tokens spent on tool descriptions vs eager MCP, at the cost of 2 extra
+ * round-trips per "new" tool the agent decides to use.
+ *
+ * Trade-off (honest): smaller models may stumble. They have to "discover"
+ * tools rather than see them all at once. If your model can't handle that,
+ * use eager mode. Test, don't assume.
+ */
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+const META_TOOLS = [
+    {
+        name: 'glyph_index',
+        description: 'List all available Glyph tools as {name, intent, riskTier}. Cheap — call this first to see what is available, then call glyph_describe for any tool you want to use.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'glyph_describe',
+        description: 'Get the full card for a single Glyph tool: input schema, output shape, side effects, reversibility, risk. Call this before glyph_invoke so you know what arguments to pass.',
+        inputSchema: {
+            type: 'object',
+            properties: { name: { type: 'string' } },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'glyph_invoke',
+        description: 'Invoke a Glyph tool by name with arguments. The arguments object must match the inputSchema you saw from glyph_describe. Returns the tool output.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                arguments: { type: 'object' },
+            },
+            required: ['name', 'arguments'],
+        },
+    },
+];
+export function mcpServerFromGlyphLazy(client, options = {}) {
+    const server = new Server({
+        name: options.serverName ?? 'glyph-mcp-bridge-lazy',
+        version: options.serverVersion ?? '0.1.0',
+    }, { capabilities: { tools: {} } });
+    // Card cache so describe/invoke don't re-fetch.
+    const cards = new Map();
+    let indexLoaded = false;
+    async function ensureIndex() {
+        if (indexLoaded)
+            return;
+        const lexicon = await client.getLexicon();
+        for (const entry of lexicon) {
+            const card = await client.getCard(entry.name, 'rich');
+            cards.set(entry.name, card);
+        }
+        indexLoaded = true;
+    }
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: META_TOOLS,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args } = req.params;
+        try {
+            if (name === 'glyph_index') {
+                await ensureIndex();
+                const entries = Array.from(cards.values()).map((c) => ({
+                    name: c.name,
+                    intent: c.intent,
+                    riskTier: c.cost.riskTier,
+                }));
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(entries) }],
+                };
+            }
+            if (name === 'glyph_describe') {
+                await ensureIndex();
+                const target = args?.name;
+                if (!target) {
+                    return errorResult('glyph_describe requires {name}');
+                }
+                const card = cards.get(target);
+                if (!card)
+                    return errorResult(`unknown glyph: ${target}`);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                name: card.name,
+                                intent: card.intent,
+                                input: card.input,
+                                output: card.output,
+                                cost: card.cost,
+                            }),
+                        },
+                    ],
+                };
+            }
+            if (name === 'glyph_invoke') {
+                await ensureIndex();
+                const p = (args ?? {});
+                if (!p.name)
+                    return errorResult('glyph_invoke requires {name}');
+                const card = cards.get(p.name);
+                if (!card)
+                    return errorResult(`unknown glyph: ${p.name}`);
+                if (card.cost.requiresConfirmation) {
+                    return errorResult(`glyph "${p.name}" requires confirmation; not supported via MCP bridge`);
+                }
+                const envelope = (await client.call(p.name, p.arguments ?? {}));
+                return envelopeToMcpResult(envelope);
+            }
+            return errorResult(`unknown meta-tool: ${name}`);
+        }
+        catch (err) {
+            return errorResult(`lazy bridge error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    return server;
+}
+function errorResult(msg) {
+    return { isError: true, content: [{ type: 'text', text: msg }] };
+}
+function envelopeToMcpResult(envelope) {
+    const blocks = [
+        {
+            type: 'text',
+            text: typeof envelope.payload === 'string'
+                ? envelope.payload
+                : JSON.stringify(envelope.payload),
+        },
+    ];
+    const inspection = envelope.inspection;
+    if (inspection && inspection.findings.length > 0) {
+        const counts = new Map();
+        for (const f of inspection.findings) {
+            counts.set(f.kind, (counts.get(f.kind) ?? 0) + f.count);
+        }
+        const breakdown = Array.from(counts.entries())
+            .map(([k, n]) => `${n} ${k}`)
+            .join(', ');
+        const total = Array.from(counts.values()).reduce((a, b) => a + b, 0);
+        blocks.push({
+            type: 'text',
+            text: `[glyph: sanitized ${total} invisible character(s) — ${breakdown}]`,
+        });
+    }
+    return { content: blocks };
+}
+export async function runStdioBridgeLazy(client, options) {
+    const server = mcpServerFromGlyphLazy(client, options);
+    await server.connect(new StdioServerTransport());
+    return server;
+}
+//# sourceMappingURL=lazy.js.map

package/dist/lazy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy.js","sourceRoot":"","sources":["../src/lazy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@glyphp/adapter-mcp-server",
+  "version": "1.0.0",
+  "description": "Expose a Glyph Protocol server's tools to any MCP client (Claude Desktop, Hermes Agent, Cursor, etc.)",
+  "license": "Apache-2.0",
+  "author": "Patrick Espino",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Monoperro0207/glyph-protocol.git",
+    "directory": "packages/adapters/mcp-server"
+  },
+  "homepage": "https://github.com/Monoperro0207/glyph-protocol#readme",
+  "bugs": "https://github.com/Monoperro0207/glyph-protocol/issues",
+  "keywords": [
+    "glyph",
+    "glyph-protocol",
+    "mcp",
+    "bridge",
+    "adapter"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@glyphp/client": "1.0.0",
+    "@glyphp/types": "1.0.0"
+  },
+  "devDependencies": {
+    "zod": "^3.23.8",
+    "@glyphp/server": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "types": "./dist/index.d.ts"
+}

package/src/index.ts

@@ -0,0 +1,255 @@
+/**
+ * @glyphp/adapter-mcp-server — expose a Glyph Protocol server's tools to any
+ * MCP client.
+ *
+ * Two modes:
+ *   - **Eager** (this file): every Glyph card surfaced as an MCP tool. Simple,
+ *     works with any MCP client, but every `tools/list` carries every schema.
+ *   - **Lazy** (`./lazy.ts`): only three meta-tools (`glyph_index`,
+ *     `glyph_describe`, `glyph_invoke`). The model navigates on demand.
+ *     Tokens spent on tool descriptions drop ~80-95% on multi-tool servers.
+ *
+ * This is the inverse direction of `@glyphp/adapter-mcp`. Together they let
+ * Glyph and MCP ecosystems consume each other.
+ *
+ * ## Honest mapping notes
+ *
+ * MCP and Glyph are not isomorphic. The bridge preserves what MCP can carry
+ * and consumes the rest server-side:
+ *
+ * - **Preserved**: tool name, intent (as description), input schema, output
+ *   payload, risk-tier as a description annotation.
+ * - **Surfaced as MCP isError**: confirmation gate refusals (when a Glyph
+ *   tool declares `requiresConfirmation`, the bridge cannot satisfy the
+ *   ticket flow for an MCP client that has no ticket concept — the call is
+ *   refused with a clear error).
+ * - **Consumed server-side**: card signatures (verified by GlyphClient),
+ *   receipt signatures (verified by GlyphClient), the SealedEnvelope's
+ *   `inspection` report — when it removed anything, a brief note is appended
+ *   to the MCP content so the calling model sees that sanitization happened.
+ * - **Lost**: the cryptographic receipt itself, the publicKey, the
+ *   attestation envelope. MCP has nowhere to put them. This is the
+ *   structural reason a security-conscious consumer should speak Glyph
+ *   natively rather than through this bridge.
+ *
+ * See `spec/tests/hermes-deepseek.md` for a worked example.
+ */
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import type { GlyphClient } from '@glyphp/client'
+import type { GlyphCard, SealedEnvelope } from '@glyphp/types'
+
+export interface BridgeOptions {
+  /** Reported as the MCP server name on handshake. */
+  serverName?: string
+  /** Reported as the MCP server version on handshake. */
+  serverVersion?: string
+  /**
+   * When false, the bridge fetches the lexicon on every `tools/list` call.
+   * When true (default), it caches per session for speed. Cache lives for
+   * the lifetime of the bridge process; restart to pick up new tools.
+   */
+  cacheLexicon?: boolean
+}
+
+/**
+ * Builds an MCP Server that exposes a Glyph server's tools. Wire it up with
+ * any transport — stdio is most common.
+ *
+ * @example
+ *   const client = new GlyphClient({ baseUrl: 'http://localhost:3199' })
+ *   const server = mcpServerFromGlyph(client)
+ *   await server.connect(new StdioServerTransport())
+ */
+export function mcpServerFromGlyph(
+  client: GlyphClient,
+  options: BridgeOptions = {}
+): Server {
+  const server = new Server(
+    {
+      name: options.serverName ?? 'glyph-mcp-bridge',
+      version: options.serverVersion ?? '0.1.0',
+    },
+    { capabilities: { tools: {} } }
+  )
+
+  /**
+   * MCP tool names match OpenAI's restriction: `^[a-zA-Z0-9_-]+$`. Glyph
+   * allows richer names (dots, slashes) — `fs.read`, `db/query`, etc. We
+   * translate by replacing every disallowed character with `_` and keep a
+   * reverse map so `tools/call` can find the original card. Collisions are
+   * caught at registration time (two glyph names that normalize to the same
+   * MCP name throw).
+   */
+  let cardCache: Map<string, GlyphCard> | undefined
+  /** mcp-safe-name → original card.name */
+  let nameAlias: Map<string, string> | undefined
+
+  const sanitizeMcpName = (name: string): string =>
+    name.replace(/[^a-zA-Z0-9_-]/g, '_')
+
+  const loadCards = async (): Promise<{
+    cards: Map<string, GlyphCard>
+    alias: Map<string, string>
+  }> => {
+    if (cardCache && nameAlias && options.cacheLexicon !== false) {
+      return { cards: cardCache, alias: nameAlias }
+    }
+    const lexicon = await client.getLexicon()
+    const cards = new Map<string, GlyphCard>()
+    const alias = new Map<string, string>()
+    for (const entry of lexicon) {
+      const card = await client.getCard(entry.name, 'rich')
+      cards.set(entry.name, card)
+      const safe = sanitizeMcpName(entry.name)
+      if (alias.has(safe)) {
+        throw new Error(
+          `MCP name collision: glyph "${entry.name}" and "${alias.get(safe)}" both normalize to "${safe}". Rename one.`
+        )
+      }
+      alias.set(safe, entry.name)
+    }
+    cardCache = cards
+    nameAlias = alias
+    return { cards, alias }
+  }
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const { cards } = await loadCards()
+    return {
+      tools: Array.from(cards.values()).map((card) => ({
+        name: sanitizeMcpName(card.name),
+        description: describeForMcp(card),
+        inputSchema: (card.input as Record<string, unknown>) ?? {
+          type: 'object',
+        },
+      })),
+    }
+  })
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params
+    const { cards, alias } = await loadCards()
+    // Accept either the MCP-safe name (what the model saw) or the original
+    // glyph name. Most clients echo the listed name verbatim.
+    const originalName = alias.get(name) ?? name
+    const card = cards.get(originalName)
+    if (!card) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `Unknown Glyph tool: ${name}` }],
+      }
+    }
+    // Glyph's confirmation gate has no MCP equivalent. Refusing here surfaces
+    // the requirement to the model rather than silently approving — which
+    // would defeat the gate's purpose.
+    if (card.cost.requiresConfirmation) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: `Glyph tool "${name}" requires confirmation. The MCP bridge cannot satisfy this flow — call this tool via a native Glyph client that supports the prepare/confirm handshake.`,
+          },
+        ],
+      }
+    }
+    try {
+      const envelope = (await client.call(
+        originalName,
+        (args ?? {}) as Record<string, unknown>
+      )) as SealedEnvelope
+      return envelopeToMcpResult(envelope)
+    } catch (err) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: `Glyph call failed: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        ],
+      }
+    }
+  })
+
+  return server
+}
+
+/**
+ * Builds the MCP `description` string the model sees. We surface the risk
+ * tier and confirmation flag in plain language so the model can reason about
+ * blast radius before invoking — matching the spirit of MCP's annotations
+ * but with the explicit Glyph vocabulary preserved.
+ */
+function describeForMcp(card: GlyphCard): string {
+  const tags: string[] = []
+  if (card.cost.riskTier !== 'safe') {
+    tags.push(`risk: ${card.cost.riskTier}`)
+  }
+  if (card.cost.sideEffects) tags.push('has side effects')
+  if (!card.cost.reversible) tags.push('not reversible')
+  if (card.cost.requiresConfirmation) tags.push('requires confirmation')
+  const suffix = tags.length > 0 ? ` (${tags.join(', ')})` : ''
+  return `${card.intent}${suffix}`
+}
+
+/**
+ * Maps a SealedEnvelope to an MCP CallToolResult. We:
+ *  - Encode the payload as a single text content block (JSON-stringified).
+ *  - If sanitization removed anything, append a brief annotation so the
+ *    model sees that Glyph defended against invisible content — this is the
+ *    only place the bridge surfaces the security work it did.
+ */
+function envelopeToMcpResult(envelope: SealedEnvelope): {
+  content: Array<{ type: string; text: string }>
+} {
+  const blocks: Array<{ type: string; text: string }> = [
+    {
+      type: 'text',
+      text:
+        typeof envelope.payload === 'string'
+          ? envelope.payload
+          : JSON.stringify(envelope.payload, null, 2),
+    },
+  ]
+  const inspection = envelope.inspection
+  if (inspection && inspection.findings.length > 0) {
+    const counts = new Map<string, number>()
+    for (const f of inspection.findings) {
+      counts.set(f.kind, (counts.get(f.kind) ?? 0) + f.count)
+    }
+    const breakdown = Array.from(counts.entries())
+      .map(([kind, count]) => `${count} ${kind}`)
+      .join(', ')
+    const total = Array.from(counts.values()).reduce((a, b) => a + b, 0)
+    blocks.push({
+      type: 'text',
+      text: `[glyph: sanitized ${total} invisible character(s) from this output — ${breakdown}]`,
+    })
+  }
+  return { content: blocks }
+}
+
+/**
+ * Convenience: builds the bridge and connects it over stdio. Useful for a
+ * one-line bin script. Resolves once the transport is wired.
+ */
+export async function runStdioBridge(
+  client: GlyphClient,
+  options?: BridgeOptions
+): Promise<Server> {
+  const server = mcpServerFromGlyph(client, options)
+  await server.connect(new StdioServerTransport())
+  return server
+}
+
+export {
+  mcpServerFromGlyphLazy,
+  runStdioBridgeLazy,
+  type LazyBridgeOptions,
+} from './lazy.js'

package/src/lazy.ts

@@ -0,0 +1,210 @@
+/**
+ * Lazy bridge mode — Glyph's actual cost-saving philosophy.
+ *
+ * Where the eager bridge (in `index.ts`) dumps every card's schema into
+ * `tools/list` (so a 50-tool server costs ~12k tokens per turn), the lazy
+ * bridge exposes **only three meta-tools** to MCP:
+ *
+ *   1. `glyph_index`   → cheap directory: [{name, oneLineIntent, riskTier}]
+ *   2. `glyph_describe` → full card for a single tool (schema, cost, etc.)
+ *   3. `glyph_invoke`  → run the underlying glyph
+ *
+ * The model navigates: list cheap → describe what it needs → invoke. Cards
+ * the agent never touches never enter context. For a 50-tool server on a
+ * 10-turn task that touches ~6 tools, this is typically an 80-95% reduction
+ * in tokens spent on tool descriptions vs eager MCP, at the cost of 2 extra
+ * round-trips per "new" tool the agent decides to use.
+ *
+ * Trade-off (honest): smaller models may stumble. They have to "discover"
+ * tools rather than see them all at once. If your model can't handle that,
+ * use eager mode. Test, don't assume.
+ */
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import type { GlyphClient } from '@glyphp/client'
+import type { GlyphCard, SealedEnvelope } from '@glyphp/types'
+
+export interface LazyBridgeOptions {
+  serverName?: string
+  serverVersion?: string
+}
+
+const META_TOOLS = [
+  {
+    name: 'glyph_index',
+    description:
+      'List all available Glyph tools as {name, intent, riskTier}. Cheap — call this first to see what is available, then call glyph_describe for any tool you want to use.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'glyph_describe',
+    description:
+      'Get the full card for a single Glyph tool: input schema, output shape, side effects, reversibility, risk. Call this before glyph_invoke so you know what arguments to pass.',
+    inputSchema: {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'glyph_invoke',
+    description:
+      'Invoke a Glyph tool by name with arguments. The arguments object must match the inputSchema you saw from glyph_describe. Returns the tool output.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        arguments: { type: 'object' },
+      },
+      required: ['name', 'arguments'],
+    },
+  },
+]
+
+export function mcpServerFromGlyphLazy(
+  client: GlyphClient,
+  options: LazyBridgeOptions = {}
+): Server {
+  const server = new Server(
+    {
+      name: options.serverName ?? 'glyph-mcp-bridge-lazy',
+      version: options.serverVersion ?? '0.1.0',
+    },
+    { capabilities: { tools: {} } }
+  )
+
+  // Card cache so describe/invoke don't re-fetch.
+  const cards = new Map<string, GlyphCard>()
+  let indexLoaded = false
+
+  async function ensureIndex(): Promise<void> {
+    if (indexLoaded) return
+    const lexicon = await client.getLexicon()
+    for (const entry of lexicon) {
+      const card = await client.getCard(entry.name, 'rich')
+      cards.set(entry.name, card)
+    }
+    indexLoaded = true
+  }
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: META_TOOLS,
+  }))
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params
+    try {
+      if (name === 'glyph_index') {
+        await ensureIndex()
+        const entries = Array.from(cards.values()).map((c) => ({
+          name: c.name,
+          intent: c.intent,
+          riskTier: c.cost.riskTier,
+        }))
+        return {
+          content: [{ type: 'text', text: JSON.stringify(entries) }],
+        }
+      }
+      if (name === 'glyph_describe') {
+        await ensureIndex()
+        const target = (args as { name?: string } | undefined)?.name
+        if (!target) {
+          return errorResult('glyph_describe requires {name}')
+        }
+        const card = cards.get(target)
+        if (!card) return errorResult(`unknown glyph: ${target}`)
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({
+                name: card.name,
+                intent: card.intent,
+                input: card.input,
+                output: card.output,
+                cost: card.cost,
+              }),
+            },
+          ],
+        }
+      }
+      if (name === 'glyph_invoke') {
+        await ensureIndex()
+        const p = (args ?? {}) as {
+          name?: string
+          arguments?: Record<string, unknown>
+        }
+        if (!p.name) return errorResult('glyph_invoke requires {name}')
+        const card = cards.get(p.name)
+        if (!card) return errorResult(`unknown glyph: ${p.name}`)
+        if (card.cost.requiresConfirmation) {
+          return errorResult(
+            `glyph "${p.name}" requires confirmation; not supported via MCP bridge`
+          )
+        }
+        const envelope = (await client.call(
+          p.name,
+          p.arguments ?? {}
+        )) as SealedEnvelope
+        return envelopeToMcpResult(envelope)
+      }
+      return errorResult(`unknown meta-tool: ${name}`)
+    } catch (err) {
+      return errorResult(
+        `lazy bridge error: ${err instanceof Error ? err.message : String(err)}`
+      )
+    }
+  })
+
+  return server
+}
+
+function errorResult(msg: string): {
+  isError: boolean
+  content: Array<{ type: string; text: string }>
+} {
+  return { isError: true, content: [{ type: 'text', text: msg }] }
+}
+
+function envelopeToMcpResult(envelope: SealedEnvelope): {
+  content: Array<{ type: string; text: string }>
+} {
+  const blocks: Array<{ type: string; text: string }> = [
+    {
+      type: 'text',
+      text:
+        typeof envelope.payload === 'string'
+          ? envelope.payload
+          : JSON.stringify(envelope.payload),
+    },
+  ]
+  const inspection = envelope.inspection
+  if (inspection && inspection.findings.length > 0) {
+    const counts = new Map<string, number>()
+    for (const f of inspection.findings) {
+      counts.set(f.kind, (counts.get(f.kind) ?? 0) + f.count)
+    }
+    const breakdown = Array.from(counts.entries())
+      .map(([k, n]) => `${n} ${k}`)
+      .join(', ')
+    const total = Array.from(counts.values()).reduce((a, b) => a + b, 0)
+    blocks.push({
+      type: 'text',
+      text: `[glyph: sanitized ${total} invisible character(s) — ${breakdown}]`,
+    })
+  }
+  return { content: blocks }
+}
+
+export async function runStdioBridgeLazy(
+  client: GlyphClient,
+  options?: LazyBridgeOptions
+): Promise<Server> {
+  const server = mcpServerFromGlyphLazy(client, options)
+  await server.connect(new StdioServerTransport())
+  return server
+}