Bürokratt MCP Server

MCP (Model Context Protocol) server for sharing AI coding assistant rules for Bürokratt modules.

Rationale: The Buerokratt tech stack, especially the DSL-based backend, is quite unique and is difficult to use with AI coding assistants. This MCP server provides a way to share rules and guidelines for different Bürokratt modules in a way that is easy to use with different IDEs and AI coding assistants. It is based on an initial .cursorrules setup that is also provided in this repo for legacy purposes.

Currently available rules:

global - Global rules that apply to all modules
Service-Module - Service Module specific rules
Buerokratt-Chatbot - Chatbot Module specific rules
shared-backend - Shared backend rules (SQL, Ruuter)
shared-frontend - Shared frontend rules (React, CSS)

Highlights

Backend expertise: Knows how to write migrations, SQL queries, and Ruuter YAML DSL.
Browser debugging: Can open browser to debug frontend issues with full console access and automatic cookie authentication. For now, this only works with Cursor!
Fork synchronization: Can sync Bürokratt module forks with upstream repositories.
Service testing: in Service Module, can test and debug services directly (similar to the test widget on service edit page).
Frontend testing: Knows how to write frontend tests for Service Module.

Planned

Add support for more modules.
Add OAuth2 support for authentication.
Consider using several MCP servers for different modules if context size is an issue. There is a CI check for this, see checks below.
Cache rules in memory if needed. Check with measure-load-time script.

Usage

In this repo folder:

docker-compose up -d

In your project folder:

Note that <project-root> can also be a folder with several Bürokratt modules.

Cursor:

<project-root>/.cursor/mcp.json

{
  "mcpServers": {
    "buerokratt-mcp": {
      "url": "http://localhost:3627/mcp"
    }
  }
}

You might also want to add a simple rule to load the rules for the module based on path. See .cursor/rules/buerokratt-mcp.mdc for an example. Place it in <project-root>/.cursor/rules/buerokratt-mcp.mdc.

VS Code:

<project-root>/.vscode/settings.json

{
  "mcp.servers": {
    "buerokratt-mcp": {
      "url": "http://localhost:3627/mcp",
      "transport": {
        "type": "sse"
      }
    }
  }
}

JetBrains:

<project-root>/.idea/mcp.json

{
  "mcpServers": {
    "buerokratt-mcp": {
      "url": "http://localhost:3627/mcp",
      "transport": {
        "type": "sse"
      }
    }
  }
}

MCP Server Features

Once configured, the MCP server provides:

Resources: Access to module-specific rules via rules://{module} (e.g., rules://Service-Module)
Tools:
- get_rules - Get rules for a specific module
- list_modules - List all available modules
- search_rules - Search rules by keyword
Prompts:
- development-rules - Get development rules as a system prompt for a specific module
Testing with MCP Inspector: pnpm inspect.

Development

Editing rules

Simply edit the rules in the rules/ folder and commit. Rules are loaded fresh on every request, so no server restart is needed to get the changes.

These rules are in Markdown format with frontmatter. modules field in frontmatter is required and should be an array of module names. Module names should match Bürokratt repository folder names exactly (e.g., Service-Module, Training-Module, Analytics-Module, Buerokratt-Chatbot). Other fields are optional. An example:

---
modules:
  - Service-Module
  - Training-Module
  - Analytics-Module
  - Buerokratt-Chatbot
tags:
  - backend
  - sql
  - database
description: Description of the rule
---

## Some rule set

... rule set content ...

⚠️ Important note on context size. To ensure the MCP server works correctly, the rule set should not exceed the following limits:

Individual files: Safe < 10 KB, Warning < 20 KB
Merged modules: Safe < 50 KB, Warning < 100 KB

This can be with an npm script, see checks below.

Project Structure

buerokratt-mcp/
├── src/              # Typescript source code
├── rules/            # Rule files (markdown with frontmatter)
│   ├── global/       # Global rules that apply to all modules
│   │   ├── common.md
│   │   └── typescript.md
│   ├── Service-Module/    # Service Module specific rules
│   │   └── rules.md
│   ├── ...other-modules...    # Other modules specific rules
│   │   └── rules.md
│   ├── shared-backend/    # Shared backend rules (SQL, Ruuter)
│   │   ├── sql-rules.md
│   │   ├── sql-restrictions.md
│   │   └── ruuter-rules.md
│   └── shared-frontend/   # Shared frontend rules (React, CSS)
│       ├── react-rules.md
│       └── css-rules.md
└── ...

Running the project for local development

# Install the correct Node version
nvm install
# Install the correct pnpm version
corepack enable pnpm
corepack use
pnpm install
pnpm start

After you are done with the code changes, rebuild the image and restart the container:

docker compose up -d --build --force-recreate

Checks

CI

The following checks run automatically in CI on push and pull requests:

format: Checks code formatting with Prettier
lint: Runs ESLint to check code quality and style
lint-markdown: Lints markdown files (rules and README) using markdownlint
typecheck: Validates TypeScript types without emitting files
validate: Validates rule files (frontmatter structure, markdown syntax, and module names against GitHub repositories)
check-context-size: Checks that rule files don't exceed safe token limits
test: Runs tests

Local

These can also be run manually with npm scripts:

pnpm format
pnpm lint
pnpm lint:markdown
pnpm typecheck
pnpm validate
pnpm check-context-size
pnpm check-context-size <module-name>
pnpm test