BugBug Unofficial MCP Server for API

Overview

This unofficial BugBug MCP (Model Context Protocol) server provides a lightweight, local-compatible API that implements the MCP interface for development, testing, and integration. It aims to simplify working with model context primitives (such as context storage, retrieval, and metadata) by offering a predictable HTTP surface you can run locally or in a container. Because it mirrors the expectations of MCP-aware clients, you can validate integrations, debug workflows, and prototype features without needing access to a remote production service.

The server is especially useful when you want deterministic behavior for automated tests, need a transparent request/response log for debugging, or want to emulate MCP responses while developing UI or backend components. The project repository (https://github.com/simplypixi/bugbug-mcp-server) contains the source and a set of usage options (local, Docker), and the server is intentionally small so you can read and adapt the code to your needs.

Features

• Simple HTTP-based MCP-compatible endpoints (context storage, retrieval, and status)
• Local-first development: run directly on your machine or inside a container
• Deterministic, inspectable responses for easier unit/integration testing
• Lightweight logging and request tracing to aid debugging
• Example clients and curl snippets to get started quickly
• Easy configuration via environment variables or .env files

Installation / Configuration

Clone the repository, install dependencies, and start the server locally:

# Clone the repo
git clone https://github.com/simplypixi/bugbug-mcp-server.git
cd bugbug-mcp-server

# Install dependencies (example for Node.js projects)
npm install

# Start in development mode
npm run dev

# Or start production mode
npm start

Recommended environment variables (create a .env at project root or export them):

# .env example
PORT=3000
LOG_LEVEL=info
STORAGE_DIR=./data
ALLOW_ANON=true

Docker usage (build and run):

# Build the image
docker build -t bugbug-mcp-server .

# Run the container
docker run -p 3000:3000 \
  -e PORT=3000 \
  -e LOG_LEVEL=info \
  -v $(pwd)/data:/app/data \
  bugbug-mcp-server

If the repository provides a different runtime (Python, Go, etc.), adjust the commands above to use the appropriate package manager and start script (pip/poetry for Python, go build/run for Go).

Available Resources

The server exposes a set of HTTP endpoints useful for development and testing. Example endpoints (adjust path prefix if configured differently):

Example: check server health

curl -v http://localhost:3000/ping

Store a context object (JSON payload):

curl -X POST http://localhost:3000/v1/context \
  -H "Content-Type: application/json" \
  -d '{"id":"ctx-123","model":"gpt-example","content":"some context data","tags":["test","local"]}'

Retrieve it:

curl http://localhost:3000/v1/context/ctx-123

Use Cases

• API testing and CI: Run the MCP server in CI to exercise client libraries against a stable, repeatable local API rather than external endpoints. This reduces flakiness and speeds up tests.
• Local integration development: Front-end or backend services that expect an MCP-compatible backend can point at the local server to develop features without network dependencies.
• Debugging and observability: Because the server is intentionally transparent, you can inspect logged requests and stored contexts to understand how your application interacts with MCP operations.
• Prototyping MCP features: Extend the server with mock model metadata, custom behaviors, or failure modes to validate how your system handles edge cases (timeouts, partial failures, malformed responses).
• Teaching and demos: Use the server as an educational tool to demonstrate the MCP lifecycle, context storage patterns, and client-side handling of MCP responses.

Tips for Developers

• Persist data to a local directory (configurable via STORAGE_DIR) to keep contexts between restarts during development.
• Use log levels to reduce noise in automated test runs (LOG_LEVEL=error) and increase detail while debugging (LOG_LEVEL=debug).
• If you need to simulate latency or errors, add middleware or a small adapter in the server code to introduce delays or random HTTP error responses.
• Write small client tests that exercise POST/GET/DELETE flows to ensure compatibility before integrating with production MCP servers.

For the latest source, issues, and contribution details, see the project on GitHub: https://github.com/simplypixi/bugbug-mcp-server.