mcp-dino

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/🦕-dino--mcp-8b5cf6?style=for-the-badge&labelColor=1a1a2e&color=a78bfa">
    <img alt="dino-mcp" src="https://img.shields.io/badge/🦕-dino--mcp-8b5cf6?style=for-the-badge&labelColor=f0f0ff&color=7c3aed">
  </picture>
</p>

<p align="center">
  <em>A production-grade MCP server with interactive HTML dashboard UI —
  written in Go, styled for delight.</em>
</p>

<div align="center">

[![Go](https://img.shields.io/badge/Go-1.25-00ADD8?logo=go&logoColor=white)](https://go.dev)
[![MCP Go SDK](https://img.shields.io/badge/MCP_Go_SDK-v1.7.0-a78bfa?logo=matrix&logoColor=white)](https://github.com/modelcontextprotocol/go-sdk)
[![Gin](https://img.shields.io/badge/Gin-1.12-0099e5?logo=go&logoColor=white)](https://github.com/gin-gonic/gin)
[![Tests](https://img.shields.io/badge/tests-7/7-22c55e?logo=checkmarx&logoColor=white)](test_mcp.sh)
[![License](https://img.shields.io/badge/license-MIT-22c55e?logo=opensourceinitiative&logoColor=white)](LICENSE)
[![Binary Size](https://img.shields.io/badge/size-~11MB-d97706?logo=files&logoColor=white)](#)

</div>

---

## 📋 Table of Contents

- [What — and Why](#-what--and-why)
- [Quick Start](#-quick-start)
- [Architecture at a Glance](#-architecture-at-a-glance)
- [Features](#-features)
- [Try It](#-try-it)
- [Tool Reference](#-tool-reference)
- [Claude Desktop Integration](#-claude-desktop-integration)
- [Development](#-development)
- [Documentation Map](#-documentation-map)
- [Project Status](#-project-status)

---

## 🦕 What — and Why

**dino-mcp** is a reference implementation of the **Model Context Protocol (MCP)** in Go that demonstrates every layer of the modern MCP stack:

| Layer | Implementation | Why it matters |
|-------|---------------|----------------|
| **Transport** | `stdio` + `Streamable HTTP` | Works in Claude Desktop AND web browsers |
| **MCP Apps** | `@modelcontextprotocol/ext-apps` `App` class | Interactive HTML UIs in Claude Desktop iframes |
| **Tools** | `dino_think`, `dino_ask`, `dino_dashboard` | Typed Go handlers, structured JSON results |
| **Resources** | `//go:embed` HTML → `text/html;profile=mcp-app` | Self-contained ~11MB binary, zero deps at runtime |

> Whether you're building an MCP server from scratch, learning the MCP Apps protocol, or need a Go — Gin — ext-apps SDK integration blueprint, this project has you covered.

---

## ⚡ Quick Start

```bash
# 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
```

<details>
<summary><b>Expected output</b> — click to expand</summary>

```
=== 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"
```
</details>

---

## 🏗 Architecture at a Glance

```mermaid
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
```

**Data flows through three pipes:**

| Pipe | Protocol | Client | Use case |
|------|----------|--------|----------|
| **MCP Tools** | JSON-RPC over stdio | Claude Desktop | Text tools (`dino_think`, `dino_ask`) |
| **MCP Apps** | JSON-RPC over stdio + postMessage | Claude Desktop iframe | Interactive UI (`dino_dashboard`) |
| **Standalone** | HTTP GET | Browser | Direct access (`/dashboard`, `/api/dinosaurs`) |

---

## ✨ Features

<details open>
<summary><b>MCP Standards Compliance</b></summary>

| Feature | Status | Notes |
|---------|--------|-------|
| Tools (`tools/list`, `tools/call`) | ✅ Complete | 3 typed tools with structured JSON responses |
| Resources (`resources/list`, `resources/read`) | ✅ Complete | `//go:embed` HTML served at `ui://` URIs |
| MCP Apps protocol | ✅ Complete | `_meta.ui.resourceUri` + `ui/initialize` handshake |
| stdio transport | ✅ | Claude Desktop, Cursor, Copilot |
| Streamable HTTP | ✅ | MCP Inspector, curl, browser, tunnel |
| SSE transport | ❌ Removed | Deprecated in MCP spec v2025-11-25 |

</details>

<details>
<summary><b>Developer Experience</b></summary>

- **3-second build cycle** — `make build-fast && make dev-http`
- **7 integration tests** — `make test` exercises every protocol method
- **Interactive debugging** — `make test-inspector` launches [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
- **Remote testing** — `make run-tunnel` creates a public `trycloudflare.com` URL
- **No API keys** — all dinosaur data is built into the binary
- **Zero runtime deps** — single static binary with embedded HTML

</details>

<details>
<summary><b>Interactive Dashboard</b></summary>

The `dino_dashboard` tool renders an HTML card grid inside Claude Desktop's iframe:

- **Filter by diet** — Carnivore, Herbivore, or show All
- **Filter by period** — Triassic, Jurassic, Cretaceous
- **12 dinosaur species** — from T-Rex to Velociraptor
- **Fallback mode** — open directly at `http://localhost:9010/dashboard`

> Note: the filter is applied server-side at the time the tool is called. Once opened with a specific filter, the in-app filter buttons can only narrow further within that same result set — they can't widen back out to species the initial call excluded.

The HTML view is built with the official `@modelcontextprotocol/ext-apps` SDK and communicates via JSON-RPC over `postMessage`.

</details>

---

## 🎮 Try It

### In Claude Desktop

```
Show me the dinosaur dashboard with carnivores
```

→ Claude detects the MCP App → renders an iframe → you see filterable dinosaur cards

### In your browser

```bash
open http://localhost:9010/dashboard
```

→ Standalone HTML with all dinosaur data fetched from the built-in REST API

### With MCP Inspector

```bash
make test-inspector
```

→ Opens `http://localhost:5173` → connects to `http://localhost:9010/mcp`

### Via curl

```bash
# 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
```

---

## 🔧 Tool Reference

| Tool | Type | Input | Output | Example Prompt |
|------|------|-------|--------|----------------|
| `dino_think` | Text | `{}` | Random fact + species JSON | "Tell me a dinosaur fact" |
| `dino_ask` | Text | `{"question": "..."}` | Answer + question JSON | "What did T-Rex eat?" |
| `dino_dashboard` | **MCP App** | `{"filter": "Carnivore"}` | HTML iframe + JSON data | "Show me carnivore dinosaurs" |

> `dino_ask` currently returns the same general dinosaur-era overview regardless of the question asked — it doesn't yet branch on the question text. Tracked as a known limitation.

Example `dino_think` response:

```json
{
  "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"
  }
}
```

Example `dino_dashboard` response:

```json
{
  "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 Integration

### CLI Mode (stdin/stdout)

Locate the binary and add to your `claude_desktop_config.json`:

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