Magic 8 Ball Server

A demo Model Context Protocol server that implements a classic Magic 8-Ball oracle. Built with TypeScript and Bun.

What's Inside

MCP Primitive	Name	Description
Tool	shake	Ask a yes/no question, get a random 8-Ball answer
Prompt	ask-the-8-ball	Reusable prompt template for consulting the oracle
Resource	magic-8-ball://responses	The complete list of 20 classic responses

Prerequisites

• Bun v1.0+
• Claude Desktop (for installing the .mcpb bundle)

Getting Started

# Install dependencies
bun install

# Run the server directly (stdio transport)
bun run start

Testing with MCP Inspector

The MCP Inspector provides a browser UI for interacting with your server.

bun run inspect

This opens http://localhost:6274 where you can:

1. Tools — Call shake with a question and see random 8-Ball responses
2. Prompts — Get the ask-the-8-ball prompt template with a question filled in
3. Resources — Read magic-8-ball://responses to see all 20 classic answers

Building & Packaging for Claude Desktop

1. Build

Compile TypeScript to JavaScript so the bundle can run with Node.js (which ships with Claude Desktop):

bun run build

This creates dist/index.js — a single-file bundle with all dependencies included.

2. Create the manifest

If you haven't already, initialize the MCPB manifest:

bunx @anthropic-ai/mcpb init

A manifest.json is already included in this repo. You can validate it:

bunx @anthropic-ai/mcpb validate manifest.json

3. Pack

bunx @anthropic-ai/mcpb pack .

This creates a .mcpb file (e.g., magic-8-ball-mcp-1.0.0.mcpb).

4. Install in Claude Desktop

Double-click the .mcpb file (or open it with Claude Desktop). Claude will show an installation dialog — click Install and the Magic 8-Ball tools will be available in your conversations.

Project Structure

bun-demo-mcp/
├── .claude/
│   └── CLAUDE.md         # Claude Code project instructions
├── dist/
│   └── index.js          # Compiled bundle (generated)
├── src/
│   ├── index.ts          # MCP server (tool + prompt + resource)
│   └── responses.ts
├── bun.lock
├── manifest.json         # MCPB bundle manifest
├── package.json
├── README.md
└── tsconfig.json

License

MIT