mdinject

Markdown prompt injection for CLI tools, with comprehensive MCP (Model Context Protocol) server integration for AI-powered automation.

Quick Links

• Features
• Installation
• Quick Start
• MCP Server Integration
• CI/CD Pipeline

Quality & CI

Crackerjack is used as the repo-wide quality-control and CI/CD gate for mdinject. Keep local lint, type, test, and security checks aligned with that workflow.

Features

Core Functionality

• Prompt Management: Create, read, update, and delete markdown prompts with SQLite storage
• Multi-Format Export: Export prompts to JSON, Markdown, or plain text formats
• CLI Integration: Inject prompts directly into terminal sessions (Claude Code, Codex, Vibe, Qwen)
• Collaborative Planning: AI-human iterative planning workflow with cache-based storage

MCP Server Integration

• 28 AI-Automatable Tools across 7 categories:

  • Prompt Storage (7 tools): Full CRUD operations with sorting and bulk operations
  • Terminal Management (5 tools): PTY spawning, writing, resizing, and profile management
  • Format (5 tools): Content formatting and sanitization for prompts and configuration
  • Export (2 tools): Multi-format export with Pro features
  • Licensing (3 tools): Status checking and license key management
  • Collaboration (4 tools): Plan creation, editing, and finalization
  • Widget (2 tools): macOS SwiftUI widget integration for quick prompt access

• Two Transport Modes:

  • STDIO: Direct integration with Claude Desktop
  • HTTP: RESTful API for external tools and development

Licensing Tiers

• Free: Single workspace prompt, clear canvas, basic features
• Pro: Multi-prompt library, export, bulk operations, advanced features

Debug override (dev/testing only):

• CLI: mdinject-mcp --license-mode auto|pro|none|trial
• Env: MDINJECT_LICENSE_MODE=auto|pro|none|trial

Installation

Prerequisites

• Python 3.13+
• uv package manager
• Git

Install from Source

# Clone the repository
git clone <your-mdinject-fork-url>
cd mdinject

# Install with uv
uv sync --all-extras

# Verify installation
uv run mdinject-mcp --help

Install from PyPI (coming soon)

pip install mdinject
# or
uv pip install mdinject

Quick Start

As a Python Package

import asyncio
from mdinject.storage import PromptStore

async def main():
    # Initialize storage
    store = PromptStore("prompts.db")

    # Create a prompt
    prompt = store.create_prompt(
        title="Code Review Checklist",
        markdown="# Review Points\n- Functionality\n- Security\n- Performance"
    )

    # List all prompts
    prompts = store.list_prompts(sort_by="title")
    for p in prompts:
        print(f"- {p.title}")

asyncio.run(main())

As an MCP Server

1. Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mdinject": {
      "command": "uv",
      "args": ["run", "mdinject-mcp"],
      "cwd": "/path/to/mdinject",
      "env": {
        "MDINJECT_MCP_DATABASE_PATH": "~/.local/share/mdinject/prompts.db"
      }
    }
  }
}

2. Restart Claude Desktop

3. Use MCP Tools

Ask Claude to:

• "Create a new prompt called 'Debug Checklist'"
• "List all my prompts sorted by title"
• "Inject the debugging prompt into my terminal"
• "Export all prompts to JSON format"

See docs/CLAUDE_DESKTOP_INTEGRATION.md for detailed setup instructions.

Example Scripts

The examples/ directory contains 4 progressive examples:

# Basic CRUD operations
uv run python examples/01_basic_prompt_management.py

# CLI injection workflow
uv run python examples/02_cli_injection_workflow.py

# Collaborative planning
uv run python examples/03_collaborative_planning.py

# Pro features demo
uv run python examples/04_pro_features_demo.py

See examples/README.md for detailed documentation.

Development

Setup Development Environment

# Clone and install
git clone <your-mdinject-fork-url>
cd mdinject
uv sync --all-extras --dev

# Install pre-commit hooks (optional)
uv run pre-commit install

Running Tests

# All tests
uv run pytest

# Tests in parallel (faster)
uv run pytest -n auto

# Unit tests only
uv run pytest -m "not integration and not slow"

# With coverage
uv run pytest --cov=mdinject --cov-report=html

Code Quality

# Format code
uv run ruff format .

# Lint code
uv run ruff check . --fix

# Security scan
uv run bandit -r mdinject/ -ll

# Check unused dependencies
uv run creosote --venv .venv

macOS Dev Quickstart

# Install JS deps for terminal/editor assets
npm install

# Build CodeMirror 6 bundle for the editor
npm run build:codemirror

# Build the Python helper (requires PyInstaller)
npm run build:helper

# Open the Xcode project
open app/MdInjectApp/MdInjectApp.xcodeproj

Running the MCP Server

# STDIO mode (for Claude Desktop)
uv run mdinject-mcp

# HTTP mode (for development)
uv run mdinject-mcp --http --http-port 8679

Documentation

• API Reference - Complete MCP tool documentation
• Claude Desktop Integration - Setup guide for Claude Desktop
• Examples - Example scripts and patterns
• App Architecture - SwiftUI + helper architecture overview
• macOS Release Guide - Build, sign, notarize, and DMG packaging
• Platform Strategy - macOS vs Linux/FreeBSD UI plan
• IPC Security - Socket permissions and auth token
• Contributing - Development guidelines
• Changelog - Version history

Architecture

System Architecture Overview

graph TB
    subgraph Frontend["Frontend Layer - User Interface"]
        SwiftUI["SwiftUI macOS (Native, Active)"]
    end

    subgraph MCP["MCP Server Layer - 28 Tools"]
        MCPServer["MCP Server (FastMCP)"]
        PromptTools["Prompt Storage (7 tools)"]
        TerminalTools["Terminal PTY (5 tools)"]
        FormatTools["Format (5 tools)"]
        ExportTools["Export (2 tools)"]
        LicenseTools["License (3 tools)"]
        CollabTools["Collaboration (4 tools)"]
        WidgetTools["Widget (2 tools)"]
    end

    subgraph Service["Service Layer - Oneiric Adapters"]
        Orchestrator["ServiceOrchestrator (Lifecycle)"]
        PromptService["PromptStorageService"]
        TerminalService["TerminalPaneService"]
        ExportService["ExportService"]
        LicenseService["LicenseService"]
    end

    subgraph Storage["Storage Layer - Data Persistence"]
        SQLite[("SQLite Database (WAL, Async)")]
        FileSystem["File System (Drafts, Config)"]
    end

    subgraph External["External Integrations"]
        ClaudeDesktop["Claude Desktop (STDIO)"]
        HTTP["HTTP API (Port 8679)"]
        PTY["PTY Processes"]
    end

    SwiftUI -->|JSON-RPC Unix Socket| MCPServer

    MCPServer --> PromptTools
    MCPServer --> TerminalTools
    MCPServer --> ExportTools
    MCPServer --> LicenseTools
    MCPServer --> CollabTools

    PromptTools --> Orchestrator
    TerminalTools --> Orchestrator
    ExportTools --> Orchestrator
    LicenseTools --> Orchestrator
    CollabTools --> Orchestrator

    Orchestrator --> PromptService
    Orchestrator --> TerminalService
    Orchestrator --> ExportService
    Orchestrator --> LicenseService

    PromptService --> SQLite
    TerminalService --> PTY
    ExportService --> SQLite
    LicenseService --> FileSystem

    ClaudeDesktop -->|STDIO| MCPServer
    MCPServer -->|HTTP| HTTP

    class SwiftUI frontend
    class MCPServer,PromptTools,TerminalTools,ExportTools,LicenseTools,CollabTools mcp
    class Orchestrator,PromptService,TerminalService,ExportService,LicenseService service
    class SQLite,FileSystem storage
    class ClaudeDesktop,HTTP,PTY external

Current Implementation (Backend Layer)

mdinject/
├── storage.py           # SQLite-based prompt storage (PromptStore, Prompt dataclass)
├── exporters.py         # Multi-format export (JSON, Markdown, Text)
├── __main__.py          # CLI entry point
└── mcp/                 # MCP server implementation
    ├── server.py        # FastMCP entry point and tool registration
    ├── server_core.py   # Lifespan management and orchestrator integration
    ├── config/          # Configuration models
    │   └── mdinject_mcp.py
    └── tools/           # 28 MCP tools across 7 categories
        ├── prompt_tools.py
        ├── terminal_tools.py
        ├── format_tools.py
        ├── export_tools.py
        ├── license_tools.py
        ├── collaboration_tools.py
        └── widget_tools.py

Planned Architecture (SwiftUI + Helper)

See docs/APP_ARCHITECTURE.md and docs/PLATFORM_STRATEGY.md for the current macOS plan, including:

• SwiftUI desktop GUI with terminal and prompt panes
• Bundled Python helper (IPC over Unix socket)
• xterm.js for terminal emulation
• CodeMirror 6 for Markdown editing
• Advanced features (templates, tags, CLI profiles)

CI/CD Pipeline

Automated Checks

Every push and PR triggers:

• ✅ Linting - Ruff format and check
• ✅ Security - Bandit vulnerability scan
• ✅ Dependencies - Creosote unused dependency check
• ✅ Unit Tests - Fast tests with coverage
• ✅ Integration Tests - MCP server lifecycle tests
• ✅ Type Checking - Mypy static analysis
• ✅ Build - Package build validation

Coverage Reports

• Coverage reports uploaded to Codecov
• HTML reports available as artifacts
• Target: >80% coverage

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development setup
• Pull request process
• Code style guidelines
• Testing guidelines
• Release process

License

BSD 3-Clause License - see LICENSE for details.

Acknowledgments

• Built with FastMCP for MCP server functionality
• Uses uv for fast, reliable package management
• Terminal emulation powered by xterm.js (planned)
• Inspired by the need for better AI-CLI integration workflows

Support

• Issues & Discussions: open an issue in the project's tracker (configured per deployment).
• Documentation: See docs/ directory

---

Status: Alpha - Backend layer complete (~25%), GUI implementation pending. MCP server fully functional with 21 tools for AI automation.