io.github.kedarvartak/md-md
MCP server for md.md - provides team knowledge context to AI assistants
Open source Open in the app JSON README (API)
About
MCP server for md.md - provides team knowledge context to AI assistants
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- kedarvartak
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.0
- Last push
- 2026-04-12T06:43:24Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-29 04:00:20
- Updated
- 2026-08-29 04:00:20
- Origin id
io.github.kedarvartak/md-md
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`).