The MarkdownLM MCP Server acts as a persistent memory and governance layer, enabling AI coding agents to query team knowledge, validate code against defined rules, and log undocumented decisions before writing or suggesting code.
Query the Knowledge Base (query_knowledge_base): Ask natural language questions about your team's documented rules, stack decisions, and architectural constraints across 10 categories (architecture, stack, testing, deployment, security, style, dependencies, error_handling, business_logic, general). Returns matching rules with sources and automatically logs gaps when no documentation exists.
Validate Code Against Team Rules (validate_code): Submit a code snippet with its purpose and category to check it against all documented team rules. Returns a pass/fail verdict with detailed violation reports — including which rule was broken and concrete fix suggestions — before code reaches a PR.
Resolve Knowledge Gaps (resolve_gap): When a decision is undocumented, log it as a knowledge gap for developer review. Returns the team's configured resolution policy: stop and ask the user (ask_user), use an AI-resolved answer (infer/markdownlm), or proceed independently (agent_decide).
Enforce Team Standards: Ensures AI agents adhere to defined rules and best practices, preventing non-compliant code from reaching pull requests.
Broad Compatibility: Configurable with Claude Code, Claude Desktop, Cursor, Windsurf, Cline, and VS Code via the same npm package.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MarkdownLM MCP Server check if this code snippet follows our security and style rules"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 elseWhen using this MCP server, always specify a category.
categoryis a required field onquery_knowledge_base.
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.
Related MCP server: RulesetMCP
Log in to MarkdownLM
Go to Settings → API & MCP
Generate an API key
Pick your tool below. All use the same npm package — one codebase, every platform.
claude mcp add markdownlm -e MARKDOWNLM_API_KEY=mdlm_your_key_here -e MARKDOWNLM_API_URL=https://markdownlm.com -- npx -y markdownlm-mcpOr 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"
}
}
}
}~/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/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"
}
}
}
}~/.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"
}
}
}
}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"
}
}
}
}.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"
}
}
}
}query_knowledge_baseQuery your team's documented rules before writing code. Returns relevant rules with sources and automatically logs gaps for undocumented decisions.
Inputs
Field | Required | Description |
| ✓ | Natural language question (e.g. "How should I handle auth?") |
| ✓ | Category of the query: |
Response — answer, sources[], gap_detected, optional gap_resolution
validate_codeValidate a code snippet against all documented rules. Returns pass/fail with violation details and fix suggestions.
Inputs
Field | Required | Description |
| ✓ | Code snippet to check |
| ✓ | What the code is supposed to do |
| ✓ | The knowledge base category relevant to this code |
Response — status (pass/fail), violations[] (rule, message, fix_suggestion), fix_suggestion
resolve_gapLog 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 |
| ✓ | The undocumented decision or question |
| ✓ | Category hint |
Response — gap_detected, resolution_mode, optional resolution, gap_id
Variable | Required | Default | Description |
| ✓ | — | API key from Settings → API & MCP |
| — |
| Override for self-hosted or staging |
100 tool calls per 60 seconds per user.
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.
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.
Copyright (c) 2026 MarkdownLM. All Rights Reserved.
MANDATORY: Call this tool before writing any code, proposing any pattern, or making any architectural or dependency decision. It queries this team's private knowledge base of documented rules, stack decisions, and architectural constraints. Do NOT rely on general knowledge — your team's rules override defaults. Returns the matching documented rules with their sources. If no documentation exists for the topic, a gap is automatically logged for the developer to review, and you MUST call resolve_gap next. The 'category' field is required — pick the single best-fit value from the allowed enum that describes the domain of your query.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language question about how to implement something or what rule applies. Be specific to the task at hand. Examples: "What authentication library should I use?", "How should errors be handled in API routes?", "What is the approved ORM for this project?" | |
| category | Yes | The knowledge base category that best matches your query domain. Required. Use "architecture" for system design, layering, module boundaries, or component relationships. Use "stack" for framework, library, or language version choices. Use "testing" for test frameworks, coverage requirements, or testing patterns. Use "deployment" for CI/CD pipelines, hosting platforms, or release processes. Use "security" for auth, authorisation, secrets management, or input validation. Use "style" for naming conventions, formatting rules, or code organisation. Use "dependencies" for approved or banned packages and version policies. Use "error_handling" for exception strategies, logging formats, or monitoring. Use "business_logic" for domain rules, workflow constraints, business invariants, pricing logic, subscription rules, or permission models. Use "general" only when no other category fits. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It discloses that the tool returns matching documented rules with their sources, and if no documentation exists, a gap is automatically logged and the agent MUST call resolve_gap next. This makes the behavior predictable and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph but contains all necessary information without redundancy. It is front-loaded with the mandatory call instruction. Slightly more structure (e.g., bullet points for category examples) could improve readability, but it is concise and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains what is returned (matching rules with sources) and the fallback behavior. It covers the tool's role in the agent's workflow, including the gap-logging mechanism and the need to call resolve_gap if no documentation exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, but the description adds significant value by providing concrete examples for the 'query' field and detailed guidance for each enum value of 'category'. This helps the agent select appropriate values beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to query a private knowledge base for documented rules, stack decisions, and architectural constraints. It distinguishes itself from siblings by specifying that if no documentation exists, the agent must call resolve_gap, and mentions sibling tools resolve_gap and validate_code in the context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'MANDATORY: Call this tool before writing any code, proposing any pattern, or making any architectural or dependency decision.' It also provides guidance on what to do if no documentation exists (call resolve_gap) and requires the 'category' field with instructions on how to choose the best-fit value from the enum.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call this when query_knowledge_base returned no documented guidance for a decision you need to make. Logs the undocumented decision as a knowledge gap so the developer can review and document it. Returns how you should proceed based on the team's configured gap policy: "ask_user" = stop and ask the developer for a decision before continuing; "infer" = MarkdownLM has auto-resolved the gap, use the returned resolution value; "agent_decide" = proceed with your best judgement and document your reasoning. Do NOT call this if query_knowledge_base returned matching rules — it is only for genuinely undocumented decisions.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | The specific undocumented decision you need to make, phrased as a question. Be precise so the developer understands exactly what is missing from the knowledge base. Example: "Which HTTP client library should I use for server-side requests — axios, got, or native fetch?" | |
| category | Yes | Category that best describes the gap. Helps the developer triage and document the missing rule. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It explains the tool logs a knowledge gap and returns a policy decision. However, it does not mention whether the operation is read-only, requires authentication, or has side effects beyond logging. While it covers essential behavior, slightly more context about safety and effects would improve transparency. Still, it is clear and accurate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear front-loading of the primary use case. It uses three sentences to convey the purpose, conditions, and expected return values. While it is moderately concise, it could be slightly more compact without losing clarity. Every sentence earns its place, but there is minor redundancy (e.g., 'undocumented decision' repeated).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, no output schema, and no annotations, the description provides a fairly complete picture. It explains the input parameters, the condition for use, and the three possible return values with actionable instructions. A minor gap is the lack of detail on what logging entails (e.g., is it persistent?), but overall it is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so the baseline is 3. The description adds some extra guidance for the 'question' parameter (phrasing as a precise question) but does not add significant meaning beyond the schema. The 'category' parameter is already fully described by the enum. Thus, minimal added value warrants a score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to be called when query_knowledge_base returns no documented guidance. It distinguishes itself from the sibling tool 'query_knowledge_base' by specifying the condition under which to use it, and explicitly says when not to call it. This meets the criteria for a specific verb+resource with sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidelines: call this only when query_knowledge_base returns no matching rules, and do NOT call it if rules exist. It explains the three possible outcomes based on the team's gap policy, giving agents clear instructions on how to proceed. This fully satisfies the dimension with explicit when/when-not and alternative behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call this after writing or editing any non-trivial function, module, or API endpoint. Checks the code snippet against this team's documented rules for the given category. Returns a pass/fail verdict plus a list of violations — each with the rule violated, the problematic location, and a concrete fix suggestion. Fix all violations before presenting the code to the developer. Do NOT skip this step even if query_knowledge_base returned no results — the validation engine runs a broader rule check.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The full code snippet to validate. Prefer complete functions or modules over partial fragments for accurate results. | |
| task | Yes | One-sentence description of what the code is supposed to do. Example: "Creates a JWT-authenticated POST /users endpoint that persists a new user to PostgreSQL." | |
| category | Yes | The category whose rules should be applied during validation. Match this to the primary concern of the code. Example: use "security" for auth middleware, "architecture" for a new service layer, "error_handling" for a try/catch wrapper, "business_logic" for domain rules or workflow invariants. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the return format (pass/fail plus violations with details) and important behavioral instruction ('Fix all violations before presenting the code'). It does not mention auth or rate limits, but the return detail is sufficient for a validation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 sentences) with every sentence earning its place. It front-loads the usage context and then details return and instructions. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains what the tool returns and how to act on results. It also integrates with sibling tool usage. It could mention error handling or limits, but overall is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaningful context beyond schema: e.g., for 'code' prefers complete functions, for 'task' gives example, for 'category' gives usage examples per scenario. This helps the agent select appropriate parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates code against team rules, with a specific verb ('checks') and resource ('code snippet'). It distinguishes itself from siblings by referencing query_knowledge_base and explaining why this step is needed even if that tool returns no results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to call ('after writing or editing any non-trivial function, module, or API endpoint') and gives a strong directive to not skip after query_knowledge_base. However, it does not explicitly list when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.0query_knowledge_baseresolve_gapvalidate_codeScored across 3 tools
The three tools map to distinct phases of a workflow: querying rules before an action, validating code after writing it, and resolving undocumented gaps. No overlap; each tool has a clear, non-conflicting purpose.
All tool names follow the same snake_case verb_noun pattern: query_knowledge_base, validate_code, resolve_gap. This is perfectly consistent and predictable.
Three tools is an appropriate size for a focused knowledge-management/validation server. Each tool is necessary and sufficient for the stated workflow, with no bloat or missing core capability.
The server covers the complete lifecycle of enforcing team rules: query relevant rules, validate code against them, and handle gaps when no rule exists. The workflow has no dead ends; every tool has a clear next step.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Your team's shipping standards, org map and delivery metrics, inside your coding agent.
Governance layer for AI coding agents: knowledge-graph grounding, session audit, policy controls.
Give your AI agent persistent, governed memory for every project. At task start it recalls the approved decisions, conventions, risks and architecture (semantic search, ranked by importance); at close it proposes what was learned as typed memories that you review and approve — governance, not a notes dump. Agents propose, humans govern: edits go back to pending and deletion is human-only by design. Connect Claude Code, Cursor, Claude Desktop or any MCP client in two minutes with just your API key — hosted (nothing to install) or locally via `uvx solucortex-mcp`. Built by SoluAI and dogfooded daily: SoluCortex is developed using its own living memory.
