{
  "markdown": "# md.md\n\nmd.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.\n\nIt combines:\n- A backend registry and policy engine\n- A React dashboard for authoring and publishing knowledge blocks\n- An MCP server for IDE and assistant integrations\n- Integration docs and product design docs\n\n## What Problem This Solves\n\nAI 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.\n\nmd.md solves this by letting teams:\n- Author knowledge once\n- Publish stable versions\n- Resolve the right context at task time\n- Reuse the same context across IDEs and AI tools\n\n## Repository Structure\n\n- `app-backend/`: NestJS API for auth, block lifecycle, policy resolution, and observability\n- `app-client/`: React + Vite dashboard for block authoring, publishing, and resolve preview\n- `mcp-server/`: Model Context Protocol server that exposes md.md tools over stdio\n- `ide-integrations/`: IDE integration documentation (currently Cursor-focused)\n- `docs/`: Product vision, phase plan, and resolution model design docs\n\n## High-Level Architecture\n\n1. Teams author Markdown files inside blocks.\n2. Blocks are versioned and published.\n3. IDE/assistant integrations call resolve tools or APIs with task context.\n4. The backend selects relevant published blocks and composes a payload.\n5. The payload is injected into AI context.\n6. Resolution and usage metadata are logged for observability.\n\n### Integration Path\n\n- IDE or AI client\n- MCP protocol over stdio\n- `mcp-server` tools\n- Backend REST API\n- Postgres persistence (Supabase-compatible)\n\n## Core Concepts\n\n### Block\nA named unit of team knowledge containing one or more Markdown files.\n\n### Draft and Published Versions\nDraft content can be edited freely. Published versions are stable and intended for consumption.\n\n### Scoped Access\nData and permissions are scoped by team and workspace.\n\n### Resolution\nAt usage time, the system resolves and composes relevant published blocks into an AI-ready payload.\n\n## Component Details\n\n## 1) Backend (`app-backend`)\n\nTech stack:\n- NestJS 11\n- PostgreSQL via `pg` (Supabase-compatible connection)\n- TypeScript\n\nResponsibilities:\n- Authentication and authorization\n- RBAC and API key management\n- Block CRUD, versioning, publishing, and archiving\n- Resolution orchestration\n- Injection log and audit log APIs\n\nNotable backend capabilities:\n- API key format: `mdmd_<token>`\n- Roles: reader, author, admin\n- Per-block permission overrides\n- Health and observability endpoints used by MCP\n\n## 2) Client Dashboard (`app-client`)\n\nTech stack:\n- React 19\n- Vite\n- TypeScript\n- MUI + Emotion\n\nResponsibilities:\n- Create and edit blocks\n- Manage block files\n- Publish versions\n- Preview resolution output\n- Configure auth/scope information for usage\n\n## 3) MCP Server (`mcp-server`)\n\nTech stack:\n- Node.js + TypeScript\n- `@modelcontextprotocol/sdk`\n- Zod for argument validation\n\nResponsibilities:\n- Expose md.md capabilities as MCP tools\n- Forward tool calls to backend APIs\n- Handle retries, timeouts, and health checks\n\nPrimary tools include:\n- `resolve_context`\n- `attach_blocks`\n- `list_blocks`\n- `get_block`\n- `health_check`\n- Block lifecycle tools (`create_block`, `update_block`, `publish_block`, etc.)\n- Access and observability tools (`whoami`, `list_injection_logs`)\n\n## 4) IDE Integrations (`ide-integrations`)\n\nContains setup patterns for connecting editors to the MCP server.\n\nCurrent documented integration:\n- Cursor (MCP client configuration)\n\n## 5) Product and Design Docs (`docs`)\n\n- `idea_1.0.md`: product rationale and system vision\n- `phases_1.0.md`: implementation roadmap (phase-oriented)\n- `resolution_model.md`: detailed target model for selection, ordering, and composition\n\n## Local Development Setup\n\n## Prerequisites\n\n- Node.js 18+\n- npm\n- PostgreSQL database (Supabase Postgres recommended)\n\n## 1) Backend\n\n```bash\ncd app-backend\nnpm install\n```\n\nCreate `app-backend/.env` with at least:\n\n```env\nSUPABASE_DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<db>\n```\n\nStart backend:\n\n```bash\nnpm run start:dev\n```\n\n## 2) Create Admin API Key\n\nFrom `app-backend`:\n\n```bash\nnpm run create-admin -- \\\n  --email admin@yourcompany.com \\\n  --name \"Admin User\" \\\n  --team team-alpha \\\n  --workspace workspace-core\n```\n\nSave the generated `mdmd_...` key securely.\n\n## 3) Client Dashboard\n\n```bash\ncd ../app-client\nnpm install\nnpm run dev\n```\n\n## 4) MCP Server\n\n```bash\ncd ../mcp-server\nnpm install\nnpm run build\nnpm start\n```\n\nSet environment variables for MCP runtime (either shell or IDE config):\n\n```env\nMD_MD_API_URL=http://localhost:3000\nMD_MD_API_KEY=mdmd_your_key_here\n```\n\n## Common Developer Workflows\n\n## Backend\n\n```bash\ncd app-backend\nnpm run start:dev\nnpm run build\nnpm run test\nnpm run test:e2e\nnpm run lint\n```\n\n## Client\n\n```bash\ncd app-client\nnpm run dev\nnpm run build\nnpm run lint\nnpm run preview\n```\n\n## MCP Server\n\n```bash\ncd mcp-server\nnpm run dev\nnpm run build\nnpm start\n```\n\n## Security and Secrets\n\n- Do not commit API keys or token files.\n- Keep secrets in environment files or secure secret managers.\n- Use least-privilege API keys for integrations.\n- Rotate keys regularly.\n- Review audit logs for sensitive actions.\n\nRecent local ignore defaults in `mcp-server/.gitignore` include:\n- `.mcpregistry_github_token`\n- `.mcpregistry_registry_token`\n\n## Current Product Status\n\nImplemented:\n- End-to-end block lifecycle (create, edit, publish)\n- Dashboard authoring and resolve preview\n- Backend RBAC and API key management\n- MCP server with tooling for context resolution and block operations\n\nIn progress or planned:\n- Smarter policy-based contextual selection and ordering\n- Expanded IDE integrations\n- Additional analytics and governance features\n\n## Where To Go Next\n\n- Backend implementation and auth docs: `app-backend/docs/`\n- MCP usage and integration details: `mcp-server/README.md`\n- IDE setup notes: `ide-integrations/README.md`\n- Product vision and roadmap: `docs/`\n\n## License\n\nSee license declarations in each package (`app-backend`, `app-client`, `mcp-server`).\n",
  "bytes": 6243,
  "sha": "c645b71532e9f3edb1f4689e0d2fac9e109454241d9576ab11f25692875568d4",
  "repo_slug": "kedarvartak/md.md",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kedarvartak_md_md_cdf8b898/readme"
}