嵌入式浏览器工具资源库

mcp-embedded-ui

A cross-language specification and shared assets for embedding a browser-based tool explorer into any MCP (Model Context Protocol) server.

Official SDKs: Python (PyPI) | TypeScript (npm) | Rust (crates.io) | [Go (Coming Soon)]

Quick Start

=== "Python" SDK: aiperceivable/mcp-embedded-ui-python

```bash
pip install mcp-embedded-ui
```

```python
from fastapi import FastAPI
from mcp_embedded_ui import create_mount

app = FastAPI()

# Mount the explorer UI to your FastAPI app
app.routes.append(create_mount(
    tools=my_tools,
    handle_call=my_handler,
    prefix="/explorer"
))

# Visit http://localhost:8000/explorer/
```

=== "TypeScript" SDK: aiperceivable/mcp-embedded-ui-typescript

```bash
npm install mcp-embedded-ui
```

```typescript
import http from "node:http";
import { createNodeHandler } from "mcp-embedded-ui";

const handler = createNodeHandler(myTools, myHandler, {
  prefix: "/explorer",
});

http.createServer(handler).listen(8000);
// Visit http://localhost:8000/explorer/
```

=== "Rust" SDK: aiperceivable/mcp-embedded-ui-rust

```toml
# Cargo.toml
[dependencies]
mcp-embedded-ui = "0.5.0"
```

```rust
use std::sync::Arc;
use mcp_embedded_ui::{create_mount, ToolsProvider, UiConfig};

// Mount the explorer UI at /explorer (pass Some("/ui") for a custom prefix)
let tools: Arc<dyn ToolsProvider> = Arc::new(my_tools);
let app = create_mount(None, tools, my_handler, UiConfig::default());

// Visit http://localhost:8000/explorer/
```

What is this?

If you build an MCP server, your users interact with tools through JSON — no visual feedback, no schema browser, no quick way to test. mcp-embedded-ui solves this by defining a standard set of HTTP endpoints and a self-contained HTML page that any MCP server can serve, in any language.

┌───────────────────────────────────┐
│  Browser                          │
│  Tool list → Schema → Try it      │
└──────────────┬────────────────────┘
               │ HTTP / JSON
┌──────────────▼────────────────────┐
│  Your MCP Server                  │
│  + mcp-embedded-ui library        │
│    (Python / TypeScript / Go / …) │
└───────────────────────────────────┘

One import. One mount. Full UI.

Key Features

The embedded explorer page provides:

• Tool list — browse all registered tools with descriptions and annotations.
• Schema inspector — expand any tool to view its full JSON Schema (inputSchema).
• Try-it console — type JSON arguments, execute the tool, see results instantly.
• cURL export — copy a ready-made cURL command for any execution.
• Auth support — enter a Bearer token in the UI, sent with all requests.

No build step. No CDN. No external dependencies. The entire UI is a single HTML string embedded in your server binary/package.

Documentation for Developers

Feature Deep Dives

• F1: HTML Frontend
• F2: Tool Discovery API
• F3: Tool Execution API
• F4: Auth Hook
• F5: Framework Integration
• F6: Try-It Console

How to Add a New Language

1. Read the Protocol Specification — the authoritative source for endpoints and data shapes.
2. Follow the Feature Manifest implementation order: F1 → F2 → F3 → F4 → F6 → F5.
3. Use the explorer.html template (do not modify the HTML content).
4. Ensure you follow the Security Checklist.
5. Open a PR to add your implementation to this list!

Working on the Shared Template

docs/explorer.html is the source of truth. Each SDK ships a byte-identical copy and asserts it in its own suite (the "drift check"), so a change here is not finished until the copies follow.

make sync-html      # copy into every checked-out SDK repo, then commit there
make install-hooks  # one-time per clone: sync automatically after each commit

make install-hooks sets core.hooksPath to .githooks, whose post-commit runs the same script — but only for commits that actually touch docs/explorer.html. Both entry points call scripts/sync-explorer.sh; there is no second implementation to drift.

The script is deliberately conservative:

• An SDK repo that is not checked out beside this one is skipped, not an error.
• A copy already matching the template is left untouched.
• A copy matching neither this working tree nor the last commit here is refused, not overwritten — that means someone edited the SDK's copy directly, which is exactly what the drift check exists to surface.
• Copies are written but never committed; the script prints the git -C ... command for each repo that changed.

Design Principles

• Zero frontend build — No npm/webpack/CDN. Just one HTML string.
• Framework-agnostic — Standard HTTP routes that mount anywhere.
• Cross-language consistency — Identical UX across Python, TS, Go, etc.
• Secure by default — XSS protection and auth sanitization built-in.

License

Apache-2.0