AI Artefact Must Markdown MCP Server 📄🤖

A zero-friction Model Context Protocol (MCP) server built with Python and Docker that instructs, standardizes, and enforces AI Agents to store all generated artifacts (implementation plans, research notes, architecture specifications, API documentation, task logs) inside the /.aiartefact directory of the active project in clean Markdown (.md) format.

Zero Manual Runs: Once configured in your MCP settings, your IDE or AI Client (Antigravity, Claude Desktop, Cursor, Cline) automatically runs and manages the container in the background on-demand. No manual terminal commands needed!

💡 Why Use This MCP Server?

During complex coding and research sessions, AI agents often generate critical design documents, plans, and summaries directly in chat responses. These get lost across sessions.

This server solves that problem by:

1. Guiding AI Agents through system prompts and strict guidelines to persist all non-trivial documentation as structured Markdown.

2. Centralizing deliverables in a single, well-organized /.aiartefact folder at the root of your project.

3. Automating metadata indexing with YAML frontmatter, searchability, and categorization.

✨ Key Features

• 🛡️ Mandatory Markdown Storage: Directs AI agents to save and update all major artifacts inside /.aiartefact/.

• 🚀 Fully Automated Lifecycle: Starts and stops automatically in the background through standard MCP client stdio communication.

• 🐳 Zero-Path Docker Mounting: Automatically binds the current active project with .:/workspace without needing absolute paths.

• 🏷️ Automated Frontmatter: Automatically injects and parses standard metadata (title, category, tags, description, created_at, updated_at).

• 🔒 Security & Traversal Protection: Prevents path traversal vulnerabilities (../) to guarantee workspace safety.

• 🔍 Full-Text Search & Discovery: Dedicated tools for searching and filtering through all past artifacts.

⚡ Quick Setup (Auto-Run via MCP)

You do NOT need to run Docker manually from the terminal during your workflows. Just build the image once and configure your client:

Step 1: Clone & Build Docker Image (One-Time)

git clone https://github.com/ranoes/artefact-must-markdown-mcp.git
cd artefact-must-markdown-mcp
docker build -t ai-artefact-markdown-mcp:latest .

Step 2: Add to Your MCP Client Settings

Select your preferred AI client below and add the configuration snippet. The client will automatically invoke the server whenever you start coding.

🔌 MCP Client Configurations

Antigravity / Gemini IDE (mcp_config.json)

Add to ~/.gemini/config/mcp_config.json or .gemini/mcp_config.json:

{
  "mcpServers": {
    "artefact-markdown-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        ".:/workspace",
        "ai-artefact-markdown-mcp:latest"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "artefact-markdown-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        ".:/workspace",
        "ai-artefact-markdown-mcp:latest"
      ]
    }
  }
}

Cursor IDE (.cursor/mcp.json)

{
  "mcpServers": {
    "artefact-markdown-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        ".:/workspace",
        "ai-artefact-markdown-mcp:latest"
      ]
    }
  }
}

Cline / Roo Code (VS Code cline_mcp_settings.json)

{
  "mcpServers": {
    "artefact-markdown-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        ".:/workspace",
        "ai-artefact-markdown-mcp:latest"
      ],
      "disabled": false,
      "autoApprove": [
        "save_artifact",
        "read_artifact",
        "list_artifacts",
        "search_artifacts",
        "get_artifact_guidelines",
        "ensure_artifact_directory"
      ]
    }
  }
}

🐍 Alternative: Standalone Python Configuration

If you prefer running via Python directly instead of Docker:

cd artefact-must-markdown-mcp
pip install -r requirements.txt

Then add this MCP config:

{
  "mcpServers": {
    "artefact-markdown-mcp": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/artefact-must-markdown-mcp",
      "env": {
        "WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}

🛠 MCP Interface Reference

MCP Tools

MCP Resources

• artifact://policy: Strict instruction defining the markdown storage requirement.

• artifact://guidelines: Best practices for organizing and naming markdown artifacts.

• artifact://list: Dynamic JSON view of all currently saved artifacts.

MCP Prompts

• enforce_markdown_artifact_policy: Injects the mandatory rule instructing AI agents to store all major deliverables into .aiartefact.

• create_project_plan_artifact: Prompt template for creating structured project implementation plans.

📝 Markdown & Frontmatter Standard

Every artifact created via save_artifact is formatted with standard frontmatter:

---
title: "System Architecture & Database Design"
category: "docs"
description: "High-level microservices architecture and PostgreSQL database schema"
tags: ["architecture", "backend", "database"]
created_at: "2026-09-10T22:00:00+07:00"
updated_at: "2026-09-10T22:00:00+07:00"
---

# System Architecture & Database Design

## 1. Overview
The system utilizes a modular service architecture...

🧪 Running Tests

Run the automated test suite with Python's built-in unittest:

python -m unittest discover tests

Output:

.......
----------------------------------------------------------------------
Ran 7 tests in 0.052s

OK

📜 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.