mcp-dino

生产级 MCP 服务，配备交互式 HTML 仪表盘 UI — 以 Go 编写，精心设计，令人愉悦。

📋 目录

• 是什么 — 为什么
• 快速开始
• 架构概览
• 功能特性
• 试用
• 工具参考
• Claude Desktop 集成
• 开发
• 文档索引
• 项目状态

🦕 是什么 — 为什么

dino-mcp 是一个使用 Go 实现的 Model Context Protocol（MCP） 参考实现，展示了现代 MCP 技术栈的每一层：

无论你是要从头构建 MCP 服务、学习 MCP Apps 协议，还是需要 Go — Gin — ext-apps SDK 集成蓝图，本项目都能满足你的需求。

⚡ 快速开始

# Clone & enter
git clone https://github.com/shennawardana23/mcp-dino.git && cd mcp-dino

# Build & run in one shot (≈2 seconds)
make build-fast && make dev-http

# Open the standalone dashboard
open http://localhost:9010/dashboard

=== dino-mcp server ===
Transport: http
Listening on :9010

[GIN] 2026/06/21 - 12:30:00 | 200 | 4.2ms | ::1 | GET "/dashboard"
[GIN] 2026/06/21 - 12:30:01 | 200 | 2.1ms | ::1 | GET "/api/dinosaurs"

🏗 架构概览

flowchart TB
  subgraph CLI["CLI Layer"]
    STDIO["stdio subcommand"]
    HTTP["http subcommand"]
  end

  subgraph SERVER["Server (internal/server/)"]
    GIN["Gin Router :9010"]
    MCPH["MCP StreamableHTTPHandler"]
    CORS["CORS Middleware"]
    TOOLS["Tools: think · ask · dashboard"]
    RES["Resources: //go:embed HTML"]
  end

  subgraph UI["View (ui/src/)"]
    APP["ext-apps App class"]
    POST["postMessage protocol"]
  end

  subgraph FALLBACK["Standalone Fallback"]
    DASH["/dashboard (HTML)"]
    API["/api/dinosaurs (JSON)"]
  end

  CLI --> GIN
  GIN --> CORS
  CORS --> MCPH
  MCPH --> TOOLS
  TOOLS --> RES
  RES --> APP
  APP --> POST
  MCPH -.->|"MCP Apps"| APP
  GIN -.->|"direct route"| DASH
  GIN -.->|"direct route"| API

  style CLI fill:#1a1a2e,color:#e0e0e0,stroke:#2d2a44
  style SERVER fill:#1a1a2e,color:#e0e0e0,stroke:#2d2a44
  style UI fill:#1a1a2e,color:#e0e0e0,stroke:#2d2a44
  style FALLBACK fill:#1a1a2e,color:#e0e0e0,stroke:#2d2a44
  style STDIO fill:#2d2a44,color:#a78bfa
  style HTTP fill:#2d2a44,color:#a78bfa
  style GIN fill:#0099e5,color:#fff
  style MCPH fill:#a78bfa,color:#fff
  style TOOLS fill:#22c55e,color:#fff
  style RES fill:#22c55e,color:#fff
  style APP fill:#facc15,color:#000
  style POST fill:#facc15,color:#000
  style DASH fill:#f87171,color:#fff
  style API fill:#f87171,color:#fff

数据通过三条管道流动：

✨ 功能

🎮 试用

在 Claude Desktop 中

Show me the dinosaur dashboard with carnivores

→ Claude 检测到 MCP App → 渲染 iframe → 你会看到可筛选的恐龙卡片

在浏览器中

open http://localhost:9010/dashboard

→ 独立 HTML 页面，所有恐龙数据均从内置 REST API 获取

使用 MCP Inspector

make test-inspector

→ 打开 http://localhost:5173 → 连接到 http://localhost:9010/mcp

通过 curl

# Initialize
curl -s -X POST http://localhost:9010/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' \
  | python3 -m json.tool

# List tools
SID="<session-id-from-above>"
curl -s -X POST http://localhost:9010/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | python3 -m json.tool

# Call dino_think
curl -s -X POST http://localhost:9010/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"dino_think","arguments":{}}}' \
  | python3 -m json.tool

🔧 工具参考

无论提问内容是什么，dino_ask 目前都会返回相同的恐龙时代概述——它尚未根据问题文本进行分支处理。此项已记录为已知限制。

dino_think 响应示例：

{
  "content": [
    { "type": "text", "text": "🦕 Did you know? The Velociraptor was only about the size of a turkey!" }
  ],
  "structuredContent": {
    "fact": "The Velociraptor was only about the size of a turkey",
    "species": "Velociraptor"
  }
}

dino_dashboard 响应示例：

{
  "content": [
    { "type": "text", "text": "Displaying dinosaur dashboard with 4 dinosaurs (filter: Carnivore)" }
  ],
  "structuredContent": {
    "filter": "Carnivore",
    "dinosaurs": [
      {
        "name": "Tyrannosaurus Rex",
        "period": "Cretaceous",
        "diet": "Carnivore",
        "length": "40 ft (12 m)",
        "weight": "9 tons (8,000 kg)",
        "funFact": "T-Rex had the strongest bite of any land animal ever",
        "imageStyle": "bg-red-900"
      }
    ],
    "timestamp": "2026-06-21T12:00:00Z"
  }
}

💬 Claude Desktop 集成

CLI 模式（stdin/stdout）

找到二进制文件，并将其添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "dino-mcp": {
      "command": "/absolute/path/to/mcp-dino/bin/dino-mcp",
      "args": ["stdio"]
    }
  }
}

保存后，重启 Claude Desktop。聊天时，工具旁会显示锤子图标（🔨）——点击即可直接调用，也可以让 Claude 自行决定。

HTTP 模式（用于调试）

make dev-http
# Server starts on :9010

🛠 开发

前置条件

命令

# Build — three options
make build            # Full: Vite UI + Go binary
make build-fast       # Quick: Go binary only (reuses existing UI)
make build-ui         # Vite UI only

# Run
make dev-http         # HTTP mode with verbose logging
make run-stdio        # stdio mode for Claude Desktop
make run-tunnel       # HTTP + Cloudflare Tunnel

# Test & verify
make test             # 7 integration tests — all must pass
make test-inspector   # Launch MCP Inspector in browser
make lint             # go vet + go fmt

# Utility
make help             # All targets with descriptions
make clean            # Remove all build artifacts

项目结构

mcp-dino/
├── bin/                          # Go build output (~11MB static binary)
├── cmd/dino-mcp/main.go          # CLI entry point (stdio | http | help)
├── internal/
│   ├── server/
│   │   └── server.go             # Composition root: mcp.Server + Gin + CORS
│   ├── tools/
│   │   ├── tools.go              # Shared types, constants, helpers
│   │   ├── think.go              # RegisterThink (dino_think tool)
│   │   ├── ask.go                # RegisterAsk (dino_ask tool)
│   │   └── dashboard.go          # RegisterDashboardTool + 12 dino species + REST API
│   └── resources/
│       ├── dashboard.go          # RegisterDashboardResource + //go:embed HTML
│       └── dashboard_ui.html     # Vite-built HTML (354KB)
├── ui/
│   └── src/
│       └── mcp-app.ts            # ext-apps App class + postMessage
├── docs/                         # Diátaxis documentation (see below)
├── test_mcp.sh                   # 7 integration tests
├── AGENTS.md                     # AI agent instructions (canonical)
├── ARCHITECTURE.md               # C4 diagrams + sequence flows
├── TECH_DESIGN.md                # Interface contracts + data model
├── Makefile                      # All targets
├── go.mod + go.sum               # Go dependencies
└── README.md                     # ← you are here

🗺 文档导航

dino-mcp 使用 Diátaxis 框架——四种文档模式，分别满足不同需求。

📊 项目状态

MVP ── Production ── Enhanced UI ── Ecosystem ── Advanced
  ●                    ○               ○             ○

构建指标

📖 延伸阅读

使用 Go、 Gin、 MCP Go SDK 和 @modelcontextprotocol/ext-apps 倾情打造