Metadata-Version: 2.5
Name: mdinject
Version: 0.2.0
Summary: An application for managing and injecting markdown prompts into CLI tools
License-File: LICENSE
Requires-Python: >=3.14
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: fastmcp>=3.4.0
Requires-Dist: httpx2
Requires-Dist: markdownify>=0.14.0
Requires-Dist: mcp-common<0.27.0,>=0.26.0
Requires-Dist: nh3
Requires-Dist: oneiric>=0.16.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: structlog>=24.0.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7.0; extra == 'dev'
Requires-Dist: crackerjack>=0.47.18; extra == 'dev'
Requires-Dist: creosote>=3.0.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.2.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: session-buddy>=0.10.12; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# mdinject

[![Code style: crackerjack](https://img.shields.io/badge/code%20style-crackerjack-000042)](https://github.com/lesleslie/crackerjack)
[![Runtime: oneiric](https://img.shields.io/badge/runtime-oneiric-6e5494)](https://github.com/lesleslie/oneiric)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Python: 3.14+](https://img.shields.io/badge/python-3.14%2B-green)](https://www.python.org/downloads/)

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

## Quick Links

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [MCP Server Integration](#mcp-server-integration)
- [CI/CD Pipeline](#cicd-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](https://github.com/astral-sh/uv) package manager
- Git

### Install from Source

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

```bash
pip install mdinject
# or
uv pip install mdinject
```

## Quick Start

### As a Python Package

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

```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](docs/CLAUDE_DESKTOP_INTEGRATION.md) for detailed setup instructions.

### Example Scripts

The `examples/` directory contains 4 progressive examples:

```bash
# 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](examples/README.md) for detailed documentation.

## Development

### Setup Development Environment

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

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

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

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

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

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

## Documentation

- **[API Reference](mdinject/mcp/API.md)** - Complete MCP tool documentation
- **[Claude Desktop Integration](docs/CLAUDE_DESKTOP_INTEGRATION.md)** - Setup guide for Claude Desktop
- **[Examples](examples/README.md)** - Example scripts and patterns
- **[App Architecture](docs/APP_ARCHITECTURE.md)** - SwiftUI + helper architecture overview
- **[macOS Release Guide](docs/RELEASE_MACOS.md)** - Build, sign, notarize, and DMG packaging
- **[Platform Strategy](docs/PLATFORM_STRATEGY.md)** - macOS vs Linux/FreeBSD UI plan
- **[IPC Security](docs/SECURITY_IPC.md)** - Socket permissions and auth token
- **[Contributing](CONTRIBUTING.md)** - Development guidelines
- **[Changelog](CHANGELOG.md)** - Version history

## Architecture

### System Architecture Overview

```mermaid
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](docs/APP_ARCHITECTURE.md) and [docs/PLATFORM_STRATEGY.md](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](CONTRIBUTING.md) for:

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

## License

BSD 3-Clause License - see [LICENSE](./LICENSE) for details.

## Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp) for MCP server functionality
- Uses [uv](https://github.com/astral-sh/uv) for fast, reliable package management
- Terminal emulation powered by [xterm.js](https://xtermjs.org/) (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.
