Beyond MCP Server

A comprehensive library for building Deno-based MCP (Model Context Protocol) servers with OAuth and workflow capabilities.

🤖 Recommended: Build with Beyond Better

We strongly recommend using Beyond Better to develop your MCP server applications!

Beyond Better is an AI-powered project assistant that revolutionizes how you build MCP servers:

Why Beyond Better for MCP Development?

🎯 Project-Wide Intelligence: BB understands your entire MCP server structure, making complex implementations easier
💬 Smart Conversations: Discuss architecture, debug issues, and refine implementations with AI assistance
⚡ Code Generation: Generate boilerplate, implement workflows, and follow best practices automatically
📚 Comprehensive Guidelines: Use our consumer-facing guidelines with BB for optimal results
🔄 Sync Documentation: Keep MCP server instructions synchronized with code changes
🛠️ Custom Tools: Extend BB with MCP-specific tools for testing and validation

Quick Start with Beyond Better

Option 1: Beyond Better Cloud (Easiest - recommended)

Sign up: Visit beyondbetter.app
Create project: Add your MCP project through the browser UI
Configure guidelines: Add guidelines-create-app.md in project settings
Start building: Chat with BB to generate your MCP server

All configuration is managed through the intuitive browser interface - no command-line needed!

Option 2: Self-Hosted / Local-Only Mode (Open source)

# 1. Install Beyond Better CLI
curl -sSL https://raw.githubusercontent.com/Beyond-Better/bb/main/install.sh | sh

# 2. Create your MCP project
mkdir my-mcp-server && cd my-mcp-server

# 3. Initialize BB
bb init

# 4. Start development with guidelines
bb start
# In BB, reference: "Use guidelines from @beyondbetter/bb-mcp-server guidelines-create-app.md"

📖 Consumer Guidelines: See guidelines-create-app.md for comprehensive instructions on building MCP servers with this library. These guidelines are specifically designed for use with LLMs and Beyond Better.

🔗 Beyond Better Resources:

Website - Get started with BB Cloud
Download - BB desktop app
Documentation - Complete BB documentation
Understanding BB - How BB works
GitHub - Open source repository

🚀 Quick Start for Users

Get started building your own MCP server in minutes with our example applications!

Installation

# Install from JSR registry
deno add jsr:@beyondbetter/bb-mcp-server

📚 Example Applications (Recommended Learning Path)

We provide 4 progressive examples that teach you everything from basic tools to advanced OAuth integration:

| Example | Complexity | Focus | What You'll Learn | |---------|------------|-------|------------------| | 1-simple | ⭐ Beginner | Basic tools & plugins | Get started with minimal setup | | 2-plugin-workflows | ⭐⭐ Intermediate | Multi-step workflows | When to use workflows vs tools | | 3-plugin-api-auth | ⭐⭐⭐ Advanced | OAuth & API integration | Third-party API authentication | | 4-manual-deps | ⭐⭐⭐⭐ Expert | Full customization | Complete infrastructure control |

🎯 Start with Example 1 - Simple MCP Server

# Clone and run the simplest example
git clone https://github.com/beyond-better/bb-mcp-server.git
cd bb-mcp-server/examples/1-simple

# Copy environment template and configure
cp .env.example .env

# Run the MCP server
deno run --allow-all --unstable-kv main.ts

✨ What you get out of the box:

✅ Working MCP server with plugin discovery
✅ Basic utility tools (datetime, system info, JSON validation)
✅ Both STDIO and HTTP transport support
✅ Environment-based configuration
✅ Comprehensive logging and error handling

📖 Complete Getting Started Guide

👉 For detailed setup instructions, architecture explanations, and step-by-step tutorials, see examples/README.md

The examples directory contains everything you need to:

🏃‍♂️ Get running quickly with working code
📚 Learn progressively from simple to advanced concepts
🧪 See testing patterns for validation and debugging
🛠️ Use as templates for your own MCP server implementations

Library Usage (Without Examples)

💡 New to building MCP servers? Check out guidelines-create-app.md for comprehensive patterns and best practices. These guidelines work great with Beyond Better for AI-assisted development.

If you prefer to start from scratch:

import { AppServer } from 'jsr:@beyondbetter/bb-mcp-server';

// Create and start server with minimal configuration
const appServer = await AppServer.create({
  serverConfig: {
    name: 'my-mcp-server',
    version: '1.0.0',
    title: 'My MCP Server',
    description: 'My custom MCP server implementation',
  },
  // Optional: plugin configuration
  pluginConfig: {
    discoveryPaths: ['./src/plugins'],
    autoLoad: true,
  },
});

await appServer.start();

Running Examples Directly from JSR

You can run any example directly without cloning the repository:

# Run the simple example
deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/1-simple

# Run the plugin-workflows example
deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/2-plugin-workflows

# Run the OAuth example
deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/3-plugin-api-auth

# Run the manual dependencies example
deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/4-manual-deps

# Run the chunked storage demo
deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/chunked-storage-demo

Note: Examples may require environment configuration (.env file) for full functionality.

✨ Key Features

🎯 Plugin System: Automatic discovery and loading of workflows and tools
🔐 OAuth Ready: Built-in OAuth provider and configurable consumer for third-party APIs
⚡ Dual Transport: STDIO and HTTP transport with session management
💾 Persistent Storage: Deno KV-based storage with automatic cleanup
📊 Comprehensive Logging: Audit trails and structured logging throughout
🔧 Type-Safe: Full TypeScript support with strict checking and validation
🧪 Testing Support: Extensive test utilities and demonstration patterns
📦 Ready for JSR: Published on JSR registry for easy installation

⚙️ Configuration Overview

The library supports comprehensive configuration via environment variables. Here are the key settings:

Essential Configuration

# Transport type
MCP_TRANSPORT=stdio|http       # Default: stdio
HTTP_PORT=3000                 # Default: 3001

# Plugin discovery
PLUGINS_DISCOVERY_PATHS=./src/plugins
PLUGINS_AUTOLOAD=true

# Storage
STORAGE_DENO_KV_PATH=./data/app.db

# Logging
LOG_LEVEL=info                 # debug|info|warn|error

# MCP Server Instructions (for LLM context)
MCP_SERVER_INSTRUCTIONS="Custom instructions for LLM..."
MCP_INSTRUCTIONS_FILE=./path/to/instructions.md

OAuth Integration

# OAuth Provider (when MCP server acts as OAuth provider)
OAUTH_PROVIDER_CLIENT_ID=your-client-id
OAUTH_PROVIDER_CLIENT_SECRET=your-client-secret

# OAuth Consumer (for third-party API integration)
OAUTH_CONSUMER_PROVIDER=example
OAUTH_CONSUMER_CLIENT_ID=third-party-client-id
OAUTH_CONSUMER_CLIENT_SECRET=third-party-secret

📚 For complete configuration details, see the examples - each shows different configuration patterns.

MCP Server Instructions

MCP Server Instructions provide essential context for LLMs to understand your server's capabilities, tools, and workflows. These instructions are automatically loaded by the server and made available to MCP clients.

Configuration Options (in priority order):

Direct Configuration: MCP_SERVER_INSTRUCTIONS="Your instructions here..."
File Path: MCP_INSTRUCTIONS_FILE="./path/to/instructions.md"
Default File: Place mcp_server_instructions.md in your project root
Automatic Fallback: Library provides generic workflow-focused instructions

Why Instructions Matter:

LLM Context: Help AI models understand your server's specific capabilities
Tool Usage: Provide guidance on when and how to use different tools
Workflow Patterns: Explain complex multi-step processes and error handling
Authentication: Document OAuth requirements and security considerations
Best Practices: Share optimal usage patte

Bb MCP Server

Install / Use

README