MCP 服务器

MarkdownLM MCP Server

Provides a persistent memory and governance layer that allows AI coding agents to query documented architecture rules and validate code against team standards. It enables agents to verify compliance across categories like security and testing before suggesting changes to ensure consistency across development sessions.

README

<img src="assets/logo.png" width="48" height="48" style="vertical-align: middle; margin-right: 8px;"> MarkdownLM MCP Server

MarkdownLM is the persistent memory and governance layer between your team and your AI coding agents. Define your rules once. Enforced everywhere. Every session.

Note:

The MarkdownLM knowledge base supports the following categories for all rules, patterns, and decisions:

architecture: Layering, boundaries, system design

stack: Frameworks, libraries, versions

testing: Test frameworks, coverage, patterns

deployment: CI/CD, platforms, scripts

security: Auth, validation, secrets

style: Naming, formatting, organization

dependencies: Approved/banned packages

error_handling: Exceptions, logging, monitoring

business_logic: Domain rules, workflow constraints, business invariants, pricing logic, subscription rules, permission models

general: Anything else

When using this MCP server, always specify a category. category is a required field on query_knowledge_base.

How it works

Your team documents architecture rules, stack decisions, and patterns in MarkdownLM.
This MCP server gives AI coding agents three focused tools to query and validate against that knowledge.
Agents validate code against your rules before suggesting changes — violations never reach PRs.

Setup

1. Get your API key

Log in to MarkdownLM
Go to Settings → API & MCP
Generate an API key

2. Configure your AI tool

Pick your tool below. All use the same npm package — one codebase, every platform.

Claude Code (CLI)

claude mcp add markdownlm -e MARKDOWNLM_API_KEY=mdlm_your_key_here -e MARKDOWNLM_API_URL=https://markdownlm.com -- npx -y markdownlm-mcp

Or manually edit ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "markdownlm": {
      "command": "npx",
      "args": ["-y", "markdownlm-mcp"],
      "env": {
        "MARKDOWNLM_API_KEY": "mdlm_your_key_here",
        "MARKDOWNLM_API_URL": "https://markdownlm.com"
      }
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "markdownlm": {
      "command": "npx",
      "args": ["-y", "markdownlm-mcp"],
      "env": {
        "MARKDOWNLM_API_KEY": "mdlm_your_key_here",
        "MARKDOWNLM_API_URL": "https://markdownlm.com"
      }
    }
  }
}

Cursor

.cursor/mcp.json in your project root (project-scoped) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "markdownlm": {
      "command": "npx",
      "args": ["-y", "markdownlm-mcp"],
      "env": {
        "MARKDOWNLM_API_KEY": "mdlm_your_key_here",
        "MARKDOWNLM_API_URL": "https://markdownlm.com"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "markdownlm": {
      "command": "npx",
      "args": ["-y", "markdownlm-mcp"],
      "env": {
        "MARKDOWNLM_API_KEY": "mdlm_your_key_here",
        "MARKDOWNLM_API_URL": "https://markdownlm.com"
      }
    }
  }
}

Cline (VS Code)

In the Cline extension settings (MCP Servers):

{
  "mcpServers": {
    "markdownlm": {
      "command": "npx",
      "args": ["-y", "markdownlm-mcp"],
      "env": {
        "MARKDOWNLM_API_KEY": "mdlm_your_key_here",
        "MARKDOWNLM_API_URL": "https://markdownlm.com"
      }
    }
  }
}

VS Code (Native/Extension)

.vscode/mcp.json in your project root:

{
  "servers": {
    "markdownlm": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "markdownlm-mcp"],
      "env": {
        "MARKDOWNLM_API_KEY": "mdlm_your_key_here",
        "MARKDOWNLM_API_URL": "https://markdownlm.com"
      }
    }
  }
}

Tools

`query_knowledge_base`

Query your team's documented rules before writing code. Returns relevant rules with sources and automatically logs gaps for undocumented decisions.

Inputs

Field	Required	Description
`query`	✓	Natural language question (e.g. "How should I handle auth?")
`category`	✓	Category of the query: `architecture`, `stack`, `testing`, `deployment`, `security`, `style`, `dependencies`, `error_handling`, `business_logic`, `general`

Response — answer, sources[], gap_detected, optional gap_resolution

`validate_code`

Validate a code snippet against all documented rules. Returns pass/fail with violation details and fix suggestions.

Inputs

Field	Required	Description
`code`	✓	Code snippet to check
`task`	✓	What the code is supposed to do
`category`	✓	The knowledge base category relevant to this code

Response — status (pass/fail), violations[] (rule, message, fix_suggestion), fix_suggestion

`resolve_gap`

Log a knowledge gap for an undocumented decision. Returns how to handle it based on your preferences: markdownlm (AI resolves), ask_user (wait for human), agent_decide (proceed independently).

Inputs

Field	Required	Description
`question`	✓	The undocumented decision or question
`category`	✓	Category hint

Response — gap_detected, resolution_mode, optional resolution, gap_id

Environment variables

Variable	Required	Default	Description
`MARKDOWNLM_API_KEY`	✓	—	API key from Settings → API & MCP
`MARKDOWNLM_API_URL`	—	`https://markdownlm.com`	Override for self-hosted or staging

Rate limiting

100 tool calls per 60 seconds per user.

Logging

All tool calls are logged to stderr as newline-delimited JSON (timestamp, tool name, inputs, outcome). This is safe for stdio MCP transport and can be piped to any log aggregator.

Contributing & Security

This repository is strictly the bridge (the client), not the brain. To protect our intellectual property, infrastructure details, and customer data, please carefully review our Contributing Guidelines and Security Policy before making any modifications.