abstract-backend-mcp

abstract-backend-mcp

Reusable MCP server for Python backend development with FastAPI, MongoDB and Stackraise support.

Features

• Health & diagnostics – ping, runtime config, project health checks
• Test runner – pytest via Poetry (all, by file, keyword, node-id)
• Quality tools – ruff check, ruff format, pyright, combined suite
• FastAPI introspection – list routes, find routes, OpenAPI summary
• MongoDB operations – readonly inspection + permission-controlled writes
• Stackraise context – module detection, domain models, auth scopes, workflows, context snapshots
• Bootstrap CLI – auto-generate config files for any Python backend

Requirements

• Python >= 3.12
• Poetry

Installation

# Clone and install
git clone <repo-url> abstract-backend-mcp
cd abstract-backend-mcp
poetry install

Quick Start

# Bootstrap MCP config in your project
cd /path/to/your-project
poetry run abstract-mcp init

# Start MCP server (stdio transport)
poetry run abstract-mcp serve

# With a YAML config override
poetry run abstract-mcp serve --config mcp.project.yaml

Usage: How to Connect the MCP to Your Project

There are three ways to use this MCP server, from lightest to most integrated:

Option A: Reference from your MCP client (recommended, zero coupling)

The MCP lives in its own repo. Your project only needs a client config file (e.g. opencode.jsonc, VS Code MCP settings, etc.) pointing to it:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "abstract-mcp": {
      "type": "local",
      "command": [
        "poetry",
        "-C",
        "/path/to/coding-mcp",
        "run",
        "abstract-mcp",
        "serve",
        "--config",
        "/path/to/your-project/mcp.project.yaml"
      ],
      "enabled": true,
      "environment": {
        "PROJECT_NAME": "my-app",
        "PROJECT_ROOT": "/path/to/your-project",
        "FASTAPI_APP_PATH": "src.main:app"
      }
    }
  }
}

Pros: no dependency added to your project, one MCP repo serves multiple projects. Cons: every dev needs the MCP repo cloned locally at a known path.

Option B: Install as a local dev dependency

From your project directory:

poetry add --group dev /path/to/coding-mcp

Then you can run the CLI directly inside your project:

poetry run abstract-mcp init     # generate config files
poetry run abstract-mcp serve    # start MCP server

And point your client config to the project itself:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "abstract-mcp": {
      "type": "local",
      "command": ["poetry", "run", "abstract-mcp", "serve"],
      "enabled": true
    }
  }
}

Pros: self-contained, any dev can run poetry install and it works. Cons: adds a dev dependency; linked to a local path (or needs a registry).

Option C: Publish to a private registry (teams)

cd /path/to/coding-mcp
poetry build
poetry publish --repository your-private-registry

Then in any project:

poetry add --group dev abstract-backend-mcp

Pros: versioned, no local path coupling. Cons: requires a package registry.

Multiple projects simultaneously

Each client session spawns its own MCP process (stdio transport = 1 process per connection). You can run multiple projects at the same time without conflicts — each has its own config and its own process.

Typical workflow

1. Clone coding-mcp once on your machine
2. In your target project:
   a. Create a mcp.project.yaml with project-specific settings
   b. Point your MCP client to the server (option A, B, or C)
3. Start your client (OpenCode, VS Code, Copilot CLI, etc.)
4. The MCP exposes all configured tools to the agent

Configuration

Settings are loaded from (in order of priority):

1. Environment variables
2. .env file
3. YAML config file (via --config or CONFIG_FILE env var)
4. Built-in defaults

Key settings

| Variable | Default | Description | |---|---|---| | PROJECT_NAME | my-project | Project identifier | | ENVIRONMENT | development | Current environment | | FASTAPI_APP_PATH | app.main:app | Python import path of the FastAPI app | | MONGODB_URI | mongodb://localhost:27017 | MongoDB connection string | | MONGODB_SAMPLE_MAX_DOCUMENTS | 20 | Maximum number of sampled documents returned by MongoDB tools | | MONGODB_SAMPLE_MAX_BYTES | 65536 | Maximum total bytes returned by sample_documents | | MONGODB_SAMPLE_MAX_FIELD_CHARS | 2000 | Max characters preserved per string field in sampled documents | | ENABLE_FASTAPI_TOOLS | true | Enable FastAPI tools | | ALLOW_FASTAPI_RUNTIME_IMPORTS | false | Allow importing FastAPI runtime app for route/OpenAPI inspection | | ENABLE_MONGODB_TOOLS | true | Enable MongoDB tools | | ENABLE_STACKRAISE_TOOLS | false | Enable Stackraise tools | | ENABLE_DEEP_STACKRAISE_CONTEXT | true | Enable deep module/symbol indexing | | ALLOW_WRITE_OPERATIONS | false | Allow MongoDB writes | | REQUIRE_WRITE_CONFIRMATION | true | Require explicit confirmed=True | | ALLOWED_WRITE_COLLECTIONS | [] | Collection allowlist (empty = all) | | STACKRAISE_CONTEXT_MODE | hybrid | Extraction mode: static, runtime, hybrid | | ALLOW_RUNTIME_CONTEXT_IMPORTS | false | Allow live runtime imports during context extraction | | STACKRAISE_MODULE_ROOTS | [] | Optional glob roots for Stackraise packages | | MAX_SOURCE_CHUNK_LINES | 200 | Max lines returned by source-oriented tools | | MAX_TOTAL_SNAPSHOT_ITEMS | 500 | Global cap for deep snapshot inventories | | MAX_OUTPUT_ITEMS | 50 | Max items returned by paginated Stackraise tools | | STACKRAISE_SEARCH_MAX_PATTERN_LENGTH | 200 | Max accepted length for search_stackraise_code pattern | | STACKRAISE_SEARCH_TIMEOUT_MS | 500 | Search timeout budget in milliseconds | | STACKRAISE_SEARCH_MAX_SCANNED_LINES | 20000 | Max total scanned lines for code search | | STACKRAISE_CONTEXT_CACHE_TTL_SECONDS | 30 | Cache TTL for Stackraise context provider | | STACKRAISE_CONTEXT_CACHE_MAX_ENTRIES | 32 | Max in-memory context cache entries | | STACKRAISE_CONTEXT_FINGERPRINT_TTL_SECONDS | 1 | TTL for project fingerprint reuse before rescanning files | | REDACT_SENSITIVE_FIELDS | true | Redact secrets in all output | | PROJECT_INSTRUCTIONS_FILE | PROJECT.md | Path to project instructions file |

Cache profile recommendations

• High precision profile (always reflect file changes quickly):
• STACKRAISE_CONTEXT_FINGERPRINT_TTL_SECONDS=0
• STACKRAISE_CONTEXT_CACHE_TTL_SECONDS=0
• Balanced profile (default, better performance):
• STACKRAISE_CONTEXT_FINGERPRINT_TTL_SECONDS=1
• STACKRAISE_CONTEXT_CACHE_TTL_SECONDS=30

Use the high precision profile when actively editing many modules and you need the most up-to-date snapshot on every request.

Project Instructions (PROJECT.md)

Each project can define a PROJECT.md file that the MCP reads at startup and passes as context to the agent. This replaces the generic default instructions with project-specific goals, architecture notes, and conventions.

Format

The file uses YAML frontmatter (optional) + markdown body:

---
name: my-app
description: Document management API with electronic signatures
stack:
  - FastAPI
  - MongoDB
  - Stackraise
conventions:
  - Use Pydantic for all validation
  - Tests required for every endpoint
  - Spanish comments in domain code
---

## Objetivo

REST API for document management with workflow automation...

## Arquitectura

- backend/src/demo/ contains the main app
- Domain models in domain/
- Services in service/

## Notas para el agente

- Do not modify auth fixtures without confirmation
- Integration tests require MongoDB running locally

How it works

1. On startup, the MCP reads PROJECT.md (or the file configured in PROJECT_INSTRUCTIONS_FILE) from the project root
2. The frontmatter metadata (name, stack, conventions, description) is formatted and prepended
3. The markdown body is included as the main instructions
4. The combined text is passed to the MCP server as instructions, which the agent receives as context

Behavior

| Scenario | Result | |---|---| | PROJECT.md exists with frontmatter + body | Full instructions with metadata | | PROJECT.md exists without frontmatter | Entire file used as instructions | | PROJECT.md does not exist | Generic default instructions | | Invalid YAML frontmatter | Warning logged, body used as instructions |

Generation

Running abstract-mcp init generates a PROJECT.md template with detected stack info and placeholder sections.

Runtime access

The tool show_project_instructions lets the agent re-read the parsed PROJECT.md at any time during a session.

Tools

Health

• ping – server alive check
• show_runtime_config – sanitized settings
• list_enabled_tools – active tool groups
• check_project_health – project structure detection

Tests & Quality

• run_tests_all, run_tests_file, run_tests_keyword, run_tests_nodeid
• run_ruff_check, run_ruff_format_check, run_pyright, run_quality_suite

FastAPI

• list_routes, find_route, show_openapi_summary

When ALLOW_FASTAPI_RUNTIME_IMPORTS=false, FastAPI introspection tools return a blocked error envelope.

MongoDB

• Readonly: list_collections, sample_documents, count_documents, show_indexes
• Writes: insert_one_controlled, update_one_controlled, delete_one_controlled

MongoDB sample responses are bounded by MONGODB_SAMPLE_MAX_DOCUMENTS and respect REDACT_SENSITIVE_FIELDS for textual/key-based redaction. Additionally, payload size is bounded by MONGODB_SAMPLE_MAX_BYTES and large string fields are truncated according to MONGODB_SAMPLE_MAX_FIELD_CHARS.

Stackraise

• detect_stackraise, show_stackraise_modules
• show_stackraise_db_metadata, show_stackraise_auth_scopes
• list_stackraise_crud_resources, list_stackraise_workflows
• list_stackraise_module_tree, list_stackraise_modules
• show_stackraise_module_symbols, show_stackraise_symbol_source
• read_stackraise_module_chunk, search_stackraise_code (use_regex=false by default)
• build_stackraise_context_snapshot – full context with schema:
• project, stackraise.modules, stackraise.domain, stackraise.api
• stackraise.auth, stackraise.workflows, stackraise.frontend_contracts
• security (redacted, warnings), extraction (mode, fallback, warnings)

Recommended Stackraise flow

Use navigation in this order to keep responses compact and deterministic:

1. build_stackraise_context_snapshot(mode="hybrid")
2. list_stackraise_module_tree()
3. show_stackraise_module_symbols(module="stackraise.some_module")
4. show_stackraise_symbol_source(symbol_id="...") or read_stackraise_module_chunk(...)

For large codebases, prefer bounded tree navigation with list_stackraise_module_tree(parent_module="stackraise", depth=0, limit=50). By default, list_stackraise_module_tree uses depth=0 to avoid returning deep subtrees.

This workflow follows snapshot -> tree -> symbols -> source and avoids large payloads.

Write Operation Policy

All MongoDB writes are gated by:

1. ALLOW_WRITE_OPERATIONS must be true
2. ENVIRONMENT must not be production/prod
3. Collection must be in ALLOWED_WRITE_COLLECTIONS (if non-empty)
4. confirmed=True must be passed explicitly (when REQUIRE_WRITE_CONFIRMATION=true)

Context Extraction Modes

| Mode | Behavior | |---|---| | static | AST analysis of source files, no imports | | runtime | Live introspection of imported modules (requires ALLOW_RUNTIME_CONTEXT_IMPORTS=true) | | hybrid | Runtime with automatic fallback to static (runtime disabled by policy by default) |

Secret Redaction

When REDACT_SENSITIVE_FIELDS=true (default), context output is redacted in two layers:

• key-based redaction (password, secret, token, api_key, etc.)
• textual redaction for symbol/source content (docstrings, literals, bearer/query tokens)

Sensitive values are replaced with REDACTED.

OpenCode Integration

After running abstract-mcp init, use the generated opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "abstract-mcp": {
      "type": "local",
      "command": ["poetry", "run", "abstract-mcp", "serve"],
      "enabled": true
    }
  }
}

The generated opencode.jsonc also includes an agent block with predefined prompts:

• audit – review, quality and security assessment
• build – implementation from execution plan
• fix – remediation based on audit findings
• doc – documentation engineering (Markdown-only edits)
• plan – planning and decomposition before implementation

AGENTS.md remains a concise operational role reference and is generated alongside opencode.jsonc.

Limitations (v1)

• No HTTP/SSE transport (stdio only)
• Dependency tracing is static and best-effort (import graph only)
• Stackraise introspection is best-effort and defensive
• No advanced RPA analysis beyond detection
• MongoDB adapter uses pymongo (no async motor)

Development

poetry install
poetry run pytest -v
poetry run ruff check .