md.md

md.md is a team intelligence platform that turns internal engineering knowledge into versioned Markdown blocks, then injects the right context into AI-assisted development workflows.

It combines:

• A backend registry and policy engine
• A React dashboard for authoring and publishing knowledge blocks
• An MCP server for IDE and assistant integrations
• Integration docs and product design docs

What Problem This Solves

AI coding assistants are strong at general coding but weak on team-specific context. Without shared context, teams repeatedly re-explain standards, architecture decisions, and workflows.

md.md solves this by letting teams:

• Author knowledge once
• Publish stable versions
• Resolve the right context at task time
• Reuse the same context across IDEs and AI tools

Repository Structure

• app-backend/: NestJS API for auth, block lifecycle, policy resolution, and observability
• app-client/: React + Vite dashboard for block authoring, publishing, and resolve preview
• mcp-server/: Model Context Protocol server that exposes md.md tools over stdio
• ide-integrations/: IDE integration documentation (currently Cursor-focused)
• docs/: Product vision, phase plan, and resolution model design docs

High-Level Architecture

1. Teams author Markdown files inside blocks.
2. Blocks are versioned and published.
3. IDE/assistant integrations call resolve tools or APIs with task context.
4. The backend selects relevant published blocks and composes a payload.
5. The payload is injected into AI context.
6. Resolution and usage metadata are logged for observability.

Integration Path

• IDE or AI client
• MCP protocol over stdio
• mcp-server tools
• Backend REST API
• Postgres persistence (Supabase-compatible)

Core Concepts

Block

A named unit of team knowledge containing one or more Markdown files.

Draft and Published Versions

Draft content can be edited freely. Published versions are stable and intended for consumption.

Scoped Access

Data and permissions are scoped by team and workspace.

Resolution

At usage time, the system resolves and composes relevant published blocks into an AI-ready payload.

Component Details

1) Backend (app-backend)

Tech stack:

• NestJS 11
• PostgreSQL via pg (Supabase-compatible connection)
• TypeScript

Responsibilities:

• Authentication and authorization
• RBAC and API key management
• Block CRUD, versioning, publishing, and archiving
• Resolution orchestration
• Injection log and audit log APIs

Notable backend capabilities:

• API key format: mdmd_<token>
• Roles: reader, author, admin
• Per-block permission overrides
• Health and observability endpoints used by MCP

2) Client Dashboard (app-client)

Tech stack:

• React 19
• Vite
• TypeScript
• MUI + Emotion

Responsibilities:

• Create and edit blocks
• Manage block files
• Publish versions
• Preview resolution output
• Configure auth/scope information for usage

3) MCP Server (mcp-server)

Tech stack:

• Node.js + TypeScript
• @modelcontextprotocol/sdk
• Zod for argument validation

Responsibilities:

• Expose md.md capabilities as MCP tools
• Forward tool calls to backend APIs
• Handle retries, timeouts, and health checks

Primary tools include:

• resolve_context
• attach_blocks
• list_blocks
• get_block
• health_check
• Block lifecycle tools (create_block, update_block, publish_block, etc.)
• Access and observability tools (whoami, list_injection_logs)

4) IDE Integrations (ide-integrations)

Contains setup patterns for connecting editors to the MCP server.

Current documented integration:

• Cursor (MCP client configuration)

5) Product and Design Docs (docs)

• idea_1.0.md: product rationale and system vision
• phases_1.0.md: implementation roadmap (phase-oriented)
• resolution_model.md: detailed target model for selection, ordering, and composition

Local Development Setup

Prerequisites

• Node.js 18+
• npm
• PostgreSQL database (Supabase Postgres recommended)

1) Backend

cd app-backend
npm install

Create app-backend/.env with at least:

SUPABASE_DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<db>

Start backend:

npm run start:dev

2) Create Admin API Key

From app-backend:

npm run create-admin -- \
  --email [email protected] \
  --name "Admin User" \
  --team team-alpha \
  --workspace workspace-core

Save the generated mdmd_... key securely.

3) Client Dashboard

cd ../app-client
npm install
npm run dev

4) MCP Server

cd ../mcp-server
npm install
npm run build
npm start

Set environment variables for MCP runtime (either shell or IDE config):

MD_MD_API_URL=http://localhost:3000
MD_MD_API_KEY=mdmd_your_key_here

Common Developer Workflows

Backend

cd app-backend
npm run start:dev
npm run build
npm run test
npm run test:e2e
npm run lint

Client

cd app-client
npm run dev
npm run build
npm run lint
npm run preview

MCP Server

cd mcp-server
npm run dev
npm run build
npm start

Security and Secrets

• Do not commit API keys or token files.
• Keep secrets in environment files or secure secret managers.
• Use least-privilege API keys for integrations.
• Rotate keys regularly.
• Review audit logs for sensitive actions.

Recent local ignore defaults in mcp-server/.gitignore include:

• .mcpregistry_github_token
• .mcpregistry_registry_token

Current Product Status

Implemented:

• End-to-end block lifecycle (create, edit, publish)
• Dashboard authoring and resolve preview
• Backend RBAC and API key management
• MCP server with tooling for context resolution and block operations

In progress or planned:

• Smarter policy-based contextual selection and ordering
• Expanded IDE integrations
• Additional analytics and governance features

Where To Go Next

• Backend implementation and auth docs: app-backend/docs/
• MCP usage and integration details: mcp-server/README.md
• IDE setup notes: ide-integrations/README.md
• Product vision and roadmap: docs/

License

See license declarations in each package (app-backend, app-client, mcp-server).