md.md MCP Server

Model Context Protocol (MCP) server for md.md - provides team knowledge context to AI assistants.

What is this?

This MCP server allows AI assistants (Claude Desktop, IDEs, etc.) to automatically access your team's knowledge blocks stored in md.md. When you're coding, the AI can fetch relevant documentation, coding standards, and guidelines without manual prompting.

Quick Start

1. Install dependencies

npm install

2. Build the server

npm run build

3. Get your API key

cd ../app-backend
npm run create-admin -- \
  --email [email protected] \
  --name "Admin" \
  --team team-alpha \
  --workspace workspace-core

Save the API key that's displayed.

4. Configure environment

cp .env.example .env
# Edit .env and add your API key

5. Test the server

npm start

The server will listen on stdio for MCP protocol messages.

IDE Integration

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "md-md": {
      "command": "node",
      "args": ["/path/to/md.md/mcp-server/dist/index.js"],
      "env": {
        "MD_MD_API_URL": "http://localhost:3000",
        "MD_MD_API_KEY": "mdmd_your_key_here"
      }
    }
  }
}

VS Code (via Cline/Continue/etc.)

Add to your MCP settings:

{
  "md-md": {
    "command": "node",
    "args": ["/path/to/md.md/mcp-server/dist/index.js"],
    "env": {
      "MD_MD_API_URL": "http://localhost:3000",
      "MD_MD_API_KEY": "mdmd_your_key_here"
    }
  }
}

Cursor

1. Open Settings → Features → MCP Servers
2. Add new server:
   • Name: md-md
   • Command: node /path/to/md.md/mcp-server/dist/index.js
   • Environment: Add MD_MD_API_KEY=mdmd_your_key_here

Available Tools

The MCP server now exposes full block lifecycle and observability capabilities for IDE-grade integration.

resolve_context - Auto Selection

Primary tool - Automatically selects relevant knowledge blocks based on:

• Current task description
• File type/extension
• File path patterns
• Repository context

Example:

AI: I need context for reviewing authentication code
→ resolve_context({ task: "review auth", fileType: "ts", filePath: "src/auth/middleware.ts" })
→ Returns: Authentication guidelines, security best practices, code review checklist

Parameters:

• task (optional): Task description (e.g., "review PR", "debug API")
• fileType (optional): File extension (e.g., "ts", "py", "go")
• filePath (optional): Current file path for pattern matching
• repo (optional): Repository name or pattern

attach_blocks - Manual Selection ⭐ NEW

Quick access tool - Manually attach specific blocks when you know exactly what you need.

Use cases:

• User says: "Use the auth block"
• User types: /auth in IDE
• You need specific blocks: "Give me API and security guidelines"
• Faster than auto-selection when you know the block name/tag

Examples:

User: "Attach the auth block"
→ attach_blocks({ query: "auth" })
→ Returns: Authentication Guidelines block

User: "I need API and security rules"
→ attach_blocks({ query: "api,security" })
→ Returns: API Design block + Security Best Practices block

User: "Use coding standards"
→ attach_blocks({ query: "coding standards", matchType: "name" })
→ Returns: Exact match by block name

Parameters:

• query (required): Block name, tag, or comma-separated list
  • Single: "auth"
  • Multiple: "api,security,testing"
  • Full name: "Authentication Guidelines"
  • Tag: "coding-standards"
• matchType (optional): How to match blocks
  • "any" (default): Fuzzy search across names, tags, labels
  • "name": Search block names only
  • "tag": Search tags only

list_blocks

Discover what team knowledge exists. Useful for exploration.

Parameters:

• search (optional): Search query
• tag (optional): Filter by tag (e.g., "security", "api-design")
• status (optional): "draft" or "published"
• includeArchived (optional): Include archived blocks

get_block

Get full details of a specific block by ID.

Parameters:

• blockId (required): Block UUID

health_check

Check connection status to md.md API. Returns latency and error details.

No parameters required.

Block Lifecycle Tools

• create_block - Create a new block
• update_block - Update block metadata
• add_block_file - Add markdown file to block
• update_block_file - Update block file content
• update_block_policy - Update selection policy and triggers
• publish_block - Publish latest draft
• archive_block - Archive a block
• unarchive_block - Restore archived block
• list_block_versions - List block versions
• draft_published_diff - Show draft vs latest published changes

Access + Observability Tools

• whoami - Return current auth context and permissions
• list_injection_logs - Return injection/resolve logs for active scope

Architecture

┌─────────────┐
│ IDE/AI Tool │
└──────┬──────┘
       │ MCP Protocol (stdio)
       │
┌──────▼──────────────┐
│ md.md MCP Server    │
│                     │
│ - Tool definitions  │
│ - Error handling    │
│ - Timeout control   │
│ - Health monitoring │
└──────┬──────────────┘
       │ REST API (Bearer token)
       │
┌──────▼──────────────┐
│ md.md Backend API   │
│                     │
│ - Authentication    │
│ - Block resolution  │
│ - Policy engine     │
└─────────────────────┘

Error Handling

The MCP server implements comprehensive error handling:

Timeout Protection

• Default: 30 seconds per request
• Configurable via MD_MD_TIMEOUT
• Prevents hanging connections

Retry Logic

• Automatic retries for transient failures
• Max retries configurable via MD_MD_MAX_RETRIES
• Exponential backoff

Health Monitoring

• Periodic health checks every 60 seconds (configurable)
• Reports: healthy, degraded, or unhealthy
• Tracks latency and error messages

MCP Error Codes

• InvalidParams - Malformed tool arguments
• MethodNotFound - Unknown tool name
• InternalError - API failures, timeouts, etc.

Environment Variables

Variable	Required	Default	Description
MD_MD_API_URL	No	http://localhost:3000	md.md backend API URL
MD_MD_API_KEY	Yes	-	API key from npm run create-admin
MD_MD_TEAM_ID	No	-	Optional explicit team scope header
MD_MD_WORKSPACE_ID	No	-	Optional explicit workspace scope header
MD_MD_TIMEOUT	No	30000	Request timeout (ms)
MD_MD_MAX_RETRIES	No	3	Max retry attempts
MD_MD_RETRY_BASE_DELAY	No	250	Retry backoff base delay (ms)
MD_MD_HEALTH_INTERVAL	No	60000	Health check interval (ms)

Development

Run in dev mode

npm run dev

Build

npm run build

Test locally

# Terminal 1: Start backend
cd ../app-backend && npm run start:dev

# Terminal 2: Start MCP server
cd mcp-server && npm start

Then send MCP protocol messages via stdio to test.

Troubleshooting

"MD_MD_API_KEY environment variable is required"

• Run npm run create-admin in app-backend
• Set the key in .env or pass via IDE config

"Request timeout after 30000ms"

• Check if backend is running: curl http://localhost:3000/api/auth/whoami
• Increase timeout: MD_MD_TIMEOUT=60000

"API request failed: 401 Unauthorized"

• Verify API key is correct
• Check key hasn't been revoked
• Test with curl: curl -H "Authorization: Bearer mdmd_key" http://localhost:3000/api/blocks

Health check shows "unhealthy"

• Backend might be down
• Network issues
• Wrong MD_MD_API_URL
• Use health_check tool to see specific error

Tool not appearing in IDE

• Restart IDE after config changes
• Check MCP server logs (stderr)
• Verify paths in IDE config are absolute
• Check environment variables are set

Production Deployment

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY dist ./dist
CMD ["node", "dist/index.js"]

Systemd Service

[Unit]
Description=md.md MCP Server
After=network.target

[Service]
Type=simple
User=mdmd
WorkingDirectory=/opt/md-md/mcp-server
ExecStart=/usr/bin/node /opt/md-md/mcp-server/dist/index.js
Restart=always
Environment="MD_MD_API_URL=https://api.md.md"
Environment="MD_MD_API_KEY=mdmd_production_key"

[Install]
WantedBy=multi-user.target

Monitoring

• Health checks via health_check tool
• Monitor stderr for errors
• Track latency metrics
• Alert on "unhealthy" status

Security

• Never commit .env file - Contains API keys
• Use read-only API keys - Reader role for IDE integrations
• Rotate keys regularly - Set expiration dates
• Monitor usage - Check audit logs for suspicious activity

License

MIT

Support

For issues or questions:

1. Check troubleshooting guide above
2. Review audit logs: GET /api/auth/audit
3. Test with curl to isolate MCP vs API issues
4. Check health status: Use health_check tool

---

Next Steps:

1. Install the server
2. Configure your IDE
3. Start using team knowledge automatically!