# AI Artefact Must Markdown MCP Server 📄🤖

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED.svg?logo=docker&logoColor=white)](https://www.docker.com/)
[![Protocol](https://img.shields.io/badge/Protocol-MCP%20v1.x-orange.svg)](https://modelcontextprotocol.io/)

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)

```bash
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`:

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

---

### Claude Desktop (`claude_desktop_config.json`)

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

---

### Cursor IDE (`.cursor/mcp.json`)

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

```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:

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

Then add this MCP config:

```json
{
  "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

| Tool Name | Description | Key Parameters |
|---|---|---|
| `save_artifact` | Saves or updates a Markdown artifact in `.aiartefact/` with frontmatter. | `filename`, `content`, `title`, `category`, `tags`, `description`, `overwrite` |
| `read_artifact` | Reads an existing artifact and returns parsed metadata and body. | `filename`, `category` |
| `list_artifacts` | Lists all stored artifacts with metadata (path, size, timestamps, tags). | `category` (optional) |
| `search_artifacts` | Full-text keyword search across titles, tags, descriptions, and file content. | `query`, `category` (optional) |
| `delete_artifact` | Safely removes an artifact from the `.aiartefact/` folder. | `filename`, `category` |
| `get_artifact_guidelines` | Returns the official formatting guidelines and policies for AI agents. | - |
| `ensure_artifact_directory` | Verifies that the `.aiartefact/` folder exists and returns its paths. | - |

---

### 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:

```markdown
---
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`:

```bash
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](LICENSE) file for details.