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

• 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:

In your project folder:

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

Cursor:

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

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

JetBrains:

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

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:

⚠️ 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

Running the project for local development

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

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: