Overview

Welcome to the official Scaffold Model Context Protocol (MCP) server. Scaffold is a specialized Retrieval-Augmented Generation (RAG) system designed to provide deep, structural understanding of large codebases to LLMs and AI agents. It transforms your source code into a living knowledge graph, allowing for precise, context-aware interactions that go far beyond simple file retrieval.

This server enables MCP clients like Cursor to interface directly with the Scaffold knowledge graph, allowing them to effectively construct, maintain, and reason about complex software projects.

Table of Contents

• Features
• Setup and Quickstart
• Configuration Explained
• Available Tools
• Usage Examples
• Troubleshooting
• Contributing

Features

• Graph-Based RAG: Represents your codebase as an interconnected graph of files, classes, and functions, capturing structural relationships.
• Living Knowledge Base: Keeps the AI's understanding synchronized with your code's structure.
• Eliminate Context Blindness: Provides AI agents with project-specific architecture and logic, reducing the need for manual context feeding.
• Precise Context Injection: Delivers targeted information about code entities, including their source, documentation, and relationships.
• Hybrid Search: Combines graph-based traversal with vector search for comprehensive context retrieval.

Setup and Quickstart

Important: Scaffold is a multi-service application. Before configuring your MCP client, you must have its database dependencies (Neo4j and ChromaDB) running and accessible to Docker. The following steps will guide you through the complete setup.

Step 1: Run Database Dependencies

You must start Neo4j and ChromaDB containers on a shared Docker network so the Scaffold container can connect to them.

1. Create a Docker Network:

   docker network create scaffold-net
   

2. Run Neo4j:

   docker run -d \
     --name scaffold-neo4j \
     --network scaffold-net \
     --restart unless-stopped \
     -p 7474:7474 -p 7687:7687 \
     -v neo4j_data:/data \
     -e NEO4J_AUTH="neo4j/password" \
     neo4j:5
   

   This starts Neo4j with default user neo4j and password password.

3. Run ChromaDB:

   docker run -d \
     --name scaffold-chromadb \
     --network scaffold-net \
     --restart unless-stopped \
     -v chroma_data:/data \
     chromadb/chroma:1.0.13
   

Step 2: Configure Your MCP Client

Now, open your MCP client's configuration file (e.g., mcp.json in Cursor) and add the following server configuration. You must replace the placeholder values (<...>) with your actual setup details.

{
  "mcpServers": {
    "Scaffold": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--name", "scaffold-mcp",
        "--network", "scaffold-net",
        "-p", "8000:8080",
        "-v", "${PROJECT_PATH}:/app/codebase",
        "-e", "CHROMA_SERVER_HOST=${CHROMA_SERVER_HOST}",
        "-e", "CHROMA_SERVER_PORT=${CHROMA_SERVER_PORT}",
        "-e", "CHROMA_COLLECTION_NAME=${CHROMA_COLLECTION_NAME}",
        "-e", "NEO4J_USER=${NEO4J_USER}",
        "-e", "NEO4J_PASSWORD=${NEO4J_PASSWORD}",
        "-e", "NEO4J_URI=${NEO4J_URI}",
        "-t",
        "ghcr.io/beer-bears/scaffold:latest"
      ],
      "env": {
        "CHROMA_SERVER_HOST": "scaffold-chromadb",
        "CHROMA_SERVER_PORT": "8000",
        "CHROMA_COLLECTION_NAME": "scaffold_data",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_URI": "bolt://neo4j:password@scaffold-neo4j:7687",
        "PROJECT_PATH": "<ABSOLUTE_PATH_TO_YOUR_CODEBASE>"
      }
    }
  }
}

Configuration Explained

The env block in the JSON is where you customize the server for your environment.

Available Tools

• get_code_entity_information(entity_name: str)
  • Finds a code entity (file, class, or function) by its name.
  • Returns a rich context block including its source code, docstrings, structural relationships (e.g., "defines method X", "uses class Y"), and relevant vector chunks from the codebase.

Usage Examples

You can now ask your AI agent to use the Scaffold tool with prompts like:

• "Use the Scaffold tool to tell me about the PaymentService class."
• "Find the source code and relationships for the save_graph_to_db function using Scaffold."
• "What does the FileNode class do and what other methods use it? Use the get_code_entity_information tool."

Troubleshooting

• Error: Container exits immediately or "Connection Refused". This is the most common issue and almost always means the Scaffold container cannot connect to its database dependencies.

  1. Check Databases: Ensure the scaffold-neo4j and scaffold-chromadb containers are running (docker ps).
  2. Check Network: Verify that all three containers (the two databases and scaffold-mcp) are on the same Docker network (scaffold-net). The docker command in the args must include --network scaffold-net.
  3. Check Credentials: Double-check that the user, password, and hostnames in the env block match the running database containers.

• Error: "File not found" or path-related issues inside the container. This is likely due to an incorrect PROJECT_PATH. The value must be the absolute path to your code on your host machine. Relative paths (like . or ~/) may not work correctly depending on your MCP client.

Contributing

Scaffold is an open-source project and we welcome contributions from the community! Whether it's reporting a bug, discussing features, or submitting code, your help is valued.