# md-md [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/kedarvartak/md.md  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/md-md

## Description
MCP server for md.md - provides team knowledge context to AI assistants

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "md-md": {
    "url": "http://localhost:3000"
  }
}
```

## Documentation & README

# 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

```bash
cd app-backend
npm install
```

Create `app-backend/.env` with at least:

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

Start backend:

```bash
npm run start:dev
```

## 2) Create Admin API Key

From `app-backend`:

```bash
npm run create-admin -- \
  --email admin@yourcompany.com \
  --name "Admin User" \
  --team team-alpha \
  --workspace workspace-core
```

Save the generated `mdmd_...` key securely.

## 3) Client Dashboard

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

## 4) MCP Server

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

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

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

## Common Developer Workflows

## Backend

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

## Client

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

## MCP Server

```bash
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`).