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 data

... View full README on GitHub