mdship 0.0.0__tar.gz

mdship-0.0.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+env/
+.DS_Store

mdship-0.0.0/.idea/.gitignore

@@ -0,0 +1,3 @@
+# Default ignored files
+/shelf/
+/workspace.xml

mdship-0.0.0/.idea/encodings.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Encoding" addBOMForNewFiles="with NO BOM" />
+</project>

mdship-0.0.0/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,13 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="PyStubPackagesAdvertiser" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="ignoredPackages">
+        <list>
+          <option value="pyspark-stubs==3.0.0.dev8" />
+        </list>
+      </option>
+    </inspection_tool>
+    <inspection_tool class="ReassignedToPlainText" enabled="false" level="WARNING" enabled_by_default="false" />
+  </profile>
+</component>

mdship-0.0.0/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

mdship-0.0.0/.idea/mdship.iml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="uv (mdship)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="PyDocumentationSettings">
+    <option name="format" value="PLAIN" />
+    <option name="myDocStringFormat" value="Plain" />
+  </component>
+</module>

mdship-0.0.0/.idea/misc.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="uv (mdship)" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="uv (mdship)" project-jdk-type="Python SDK" />
+</project>

mdship-0.0.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/mdship.iml" filepath="$PROJECT_DIR$/.idea/mdship.iml" />
+    </modules>
+  </component>
+</project>

mdship-0.0.0/.idea/workspace.xml

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="57e4e07a-8725-42a0-b41e-c0333c53c14c" name="Changes" comment="" />
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="ProjectColorInfo"><![CDATA[{
+  "associatedIndex": 4
+}]]></component>
+  <component name="ProjectId" id="3EgA9ad6RYxNiPjwWPDgNaiD5hf" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "junie.onboarding.icon.badge.shown": "true",
+    "last_opened_file_path": "/Users/verhasp/github/mdship",
+    "settings.editor.selected.configurable": "preferences.pluginManager"
+  }
+}]]></component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-python-sdk-9f8e2b94138c-36ea0e71a18c-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-251.26094.141" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="57e4e07a-8725-42a0-b41e-c0333c53c14c" name="Changes" comment="" />
+      <created>1780589687264</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1780589687264</updated>
+    </task>
+    <servers />
+  </component>
+</project>

mdship-0.0.0/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "mdship": {
+      "command": "mdship",
+      "args": [
+        "mcp"
+      ]
+    }
+  }
+}

mdship-0.0.0/CLAUDE.md

@@ -0,0 +1,116 @@
+# mdship — Markdown Manipulation Tool
+
+## Project Overview
+
+**mdship** is a command-line tool and MCP (Model Context Protocol) server for manipulating markdown files. It provides utilities for fixing heading hierarchies, shifting heading levels, adding content checksums, and reflowing paragraphs.
+
+The tool runs locally with no external dependencies (except for the base Python environment) and can be invoked either as a CLI command or as an MCP server for use with Claude.
+
+---
+
+## Repository Structure
+
+```
+mdship/
+├── CLAUDE.md                  # This file
+├── README.md                  # User-facing documentation
+├── pyproject.toml             # Project definition and dependencies
+├── .mcp.json                  # MCP server configuration
+├── .gitignore
+│
+├── mdship/                    # Main package
+│   ├── __init__.py
+│   ├── cli.py                 # CLI command dispatcher (typer app)
+│   ├── markdown.py            # Core markdown manipulation functions
+│   └── mcp_server.py          # MCP server implementation
+│
+└── tests/                     # Test suite
+    ├── __init__.py
+    └── test_markdown.py       # Unit tests for markdown functions
+```
+
+---
+
+## Core Functions
+
+### `fix_heading_levels(content: str) -> str`
+
+Ensures proper heading hierarchy. Should prevent skipping levels (e.g., h1 → h3).
+
+**Status**: Skeleton only, needs implementation
+
+### `shift_heading_levels(content: str, levels: int) -> str`
+
+Shifts all headings by N levels. Positive = lower (h1 → h2), negative = raise (h2 → h1).
+
+**Status**: Basic implementation complete
+
+### `add_content_checksum(content: str, algorithm: str) -> str`
+
+Adds or updates a checksum in YAML front-matter. Supports md5, sha1, sha256.
+
+**Status**: Basic implementation complete
+
+### `reflow_paragraphs(content: str, width: Optional[int]) -> str`
+
+Reflows paragraphs to a specified width, or one sentence per line if width=0.
+
+**Status**: Basic implementation complete
+
+---
+
+## CLI Interface
+
+Commands are dispatched via `typer.Typer` in `cli.py`. Each command:
+- Takes a markdown file as an argument
+- Outputs the result to stdout
+- Exits with code 1 on error
+
+```bash
+mdship fix-headings file.md
+mdship shift-headings file.md --levels 1
+mdship add-checksum file.md --algorithm sha256
+mdship reflow file.md --width 80
+mdship mcp  # Start MCP server on stdio
+```
+
+---
+
+## MCP Integration
+
+The `mcp_server.py` module implements a stdio-based MCP server that exposes the same markdown functions as async tools. The server:
+
+- Runs on stdin/stdout only (no network)
+- Exposes tools: `fix_headings`, `shift_headings`, `add_checksum`, `reflow`
+- Handles errors gracefully and returns error messages as text content
+
+Configure in Claude's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "mdship": {
+      "command": "mdship",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Development Notes
+
+- Uses `typer` for CLI, `mcp` Python SDK for server
+- No external markdown parsing library yet; uses regex for headings
+- Front-matter assumed to be YAML between `---` delimiters
+- Code blocks (triple backticks) are preserved during reflow
+- Tests use `pytest`; use `pytest -v` for detailed output
+
+### Next Steps
+
+1. Enhance `fix_heading_levels` to properly normalize hierarchies
+2. Add more comprehensive markdown parsing (consider `markdown-it-py` or similar)
+3. Add support for different markdown flavors (GFM, CommonMark, etc.)
+4. Add recursive directory processing option
+5. Add dry-run mode to preview changes

mdship-0.0.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: mdship
+Version: 0.0.0
+Summary: CLI and MCP tool for manipulating markdown files
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'

mdship-0.0.0/README.md

@@ -0,0 +1,65 @@
+# mdship
+
+A command-line and MCP tool for manipulating markdown files.
+
+## Features
+
+- **Fix heading levels**: Ensure consistent heading hierarchy
+- **Shift headings**: Move all headings up or down by N levels
+- **Add checksums**: Insert content checksums into front-matter
+- **Reflow paragraphs**: Reflow text to a specific width or one sentence per line
+
+## Installation
+
+```bash
+uv sync
+uv run pip install -e .
+```
+
+## Usage
+
+### Command Line
+
+```bash
+mdship fix-headings file.md
+mdship shift-headings file.md --levels 1
+mdship add-checksum file.md --algorithm sha256
+mdship reflow file.md --width 80
+```
+
+### MCP Server
+
+Configure in your Claude settings:
+
+```json
+{
+  "mcpServers": {
+    "mdship": {
+      "command": "mdship",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Then use the available tools in Claude with markdown content.
+
+## Development
+
+Install dependencies:
+
+```bash
+uv sync
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+Format code:
+
+```bash
+ruff check --fix
+```

mdship-0.0.0/build.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+cd "$SCRIPT_DIR"
+
+echo "=== Syncing dependencies ==="
+uv sync --all-extras --python /opt/homebrew/bin/python3
+
+echo "=== Running tests ==="
+uv run pytest tests/ -v
+
+echo "=== Building distribution ==="
+uv build
+
+VERSION=$(uv run python -c "from importlib.metadata import version; print(version('mdship'))")
+echo "=== Built mdship $VERSION ==="

mdship-0.0.0/mdship/__init__.py

@@ -0,0 +1,3 @@
+"""mdship — CLI and MCP tool for manipulating markdown files."""
+
+__version__ = "0.1.0"

mdship-0.0.0/mdship/cli.py

@@ -0,0 +1,106 @@
+import sys
+from importlib.metadata import version as _pkg_version
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+_VERSION = _pkg_version("mdship")
+
+app = typer.Typer(
+    help=f"mdship — markdown manipulation tool (version {_VERSION})",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+err = Console(stderr=True)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        print(f"mdship {_VERSION}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    _: Annotated[
+        bool | None,
+        typer.Option("--version", "-V", callback=_version_callback, is_eager=True, help="Show version and exit."),
+    ] = None,
+) -> None:
+    pass
+
+
+@app.command()
+def fix_headings(
+    file: Annotated[Path, typer.Argument(help="Markdown file to process")],
+) -> None:
+    """Fix heading levels to ensure consistent hierarchy."""
+    if not file.exists():
+        err.print(f"[red]Error:[/red] file not found: {file}")
+        raise typer.Exit(1)
+
+    from mdship.markdown import fix_heading_levels
+
+    content = file.read_text()
+    fixed_content = fix_heading_levels(content)
+    print(fixed_content, end="")
+
+
+@app.command()
+def shift_headings(
+    file: Annotated[Path, typer.Argument(help="Markdown file to process")],
+    levels: Annotated[int, typer.Option("--levels", "-l", help="Number of levels to shift (positive=lower, negative=higher)")] = 1,
+) -> None:
+    """Shift all headings by the specified number of levels."""
+    if not file.exists():
+        err.print(f"[red]Error:[/red] file not found: {file}")
+        raise typer.Exit(1)
+
+    from mdship.markdown import shift_heading_levels
+
+    content = file.read_text()
+    shifted_content = shift_heading_levels(content, levels)
+    print(shifted_content, end="")
+
+
+@app.command()
+def add_checksum(
+    file: Annotated[Path, typer.Argument(help="Markdown file to process")],
+    algorithm: Annotated[str, typer.Option("--algorithm", "-a", help="Hash algorithm (md5, sha256, sha1)")] = "sha256",
+) -> None:
+    """Add or update checksum in front-matter."""
+    if not file.exists():
+        err.print(f"[red]Error:[/red] file not found: {file}")
+        raise typer.Exit(1)
+
+    from mdship.markdown import add_content_checksum
+
+    content = file.read_text()
+    updated_content = add_content_checksum(content, algorithm)
+    print(updated_content, end="")
+
+
+@app.command()
+def reflow(
+    file: Annotated[Path, typer.Argument(help="Markdown file to process")],
+    width: Annotated[int | None, typer.Option("--width", "-w", help="Line width (0 for one sentence per line)")] = None,
+) -> None:
+    """Reflow paragraphs to specified width or one sentence per line."""
+    if not file.exists():
+        err.print(f"[red]Error:[/red] file not found: {file}")
+        raise typer.Exit(1)
+
+    from mdship.markdown import reflow_paragraphs
+
+    content = file.read_text()
+    reflowed_content = reflow_paragraphs(content, width)
+    print(reflowed_content, end="")
+
+
+@app.command()
+def mcp() -> None:
+    """Start mdship as an MCP server on stdio."""
+    from mdship.mcp_server import main as mcp_main
+
+    mcp_main()

mdship-0.0.0/mdship/markdown.py

@@ -0,0 +1,179 @@
+"""Core markdown manipulation functions."""
+
+import hashlib
+import re
+from typing import Optional
+
+
+def fix_heading_levels(content: str) -> str:
+    """Fix heading levels to ensure consistent hierarchy.
+
+    Ensures headings follow proper nesting (no skipping from h1 to h3, etc).
+    """
+    lines = content.split("\n")
+    result = []
+    min_level = None
+
+    for line in lines:
+        match = re.match(r"^(#{1,6})\s+(.+)$", line)
+        if match:
+            level = len(match.group(1))
+            text = match.group(2)
+
+            if min_level is None:
+                min_level = level
+            else:
+                # TODO: Implement logic to adjust heading levels
+                pass
+
+            result.append(line)
+        else:
+            result.append(line)
+
+    return "\n".join(result)
+
+
+def shift_heading_levels(content: str, levels: int) -> str:
+    """Shift all headings by the specified number of levels.
+
+    Positive numbers lower the headings (h1 -> h2), negative numbers raise them (h2 -> h1).
+    """
+    lines = content.split("\n")
+    result = []
+
+    for line in lines:
+        match = re.match(r"^(#{1,6})\s+(.+)$", line)
+        if match:
+            current_level = len(match.group(1))
+            text = match.group(2)
+            new_level = max(1, min(6, current_level + levels))
+            result.append("#" * new_level + " " + text)
+        else:
+            result.append(line)
+
+    return "\n".join(result)
+
+
+def add_content_checksum(content: str, algorithm: str = "sha256") -> str:
+    """Add or update checksum in front-matter.
+
+    Supports md5, sha1, and sha256 algorithms.
+    """
+    lines = content.split("\n")
+
+    if not lines or lines[0] != "---":
+        # No YAML front-matter, prepend it
+        hash_obj = hashlib.new(algorithm)
+        hash_obj.update(content.encode())
+        checksum = hash_obj.hexdigest()
+        front_matter = f"---\nchecksum: {checksum}\nchecksum_algorithm: {algorithm}\n---\n"
+        return front_matter + content
+
+    # Find the closing --- of front-matter
+    end_idx = None
+    for i in range(1, len(lines)):
+        if lines[i] == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        # Malformed front-matter, just add at the beginning
+        hash_obj = hashlib.new(algorithm)
+        hash_obj.update(content.encode())
+        checksum = hash_obj.hexdigest()
+        front_matter = f"---\nchecksum: {checksum}\nchecksum_algorithm: {algorithm}\n---\n"
+        return front_matter + content
+
+    # Calculate checksum of the content (excluding front-matter)
+    content_without_fm = "\n".join(lines[end_idx + 1 :])
+    hash_obj = hashlib.new(algorithm)
+    hash_obj.update(content_without_fm.encode())
+    checksum = hash_obj.hexdigest()
+
+    # Update or add checksum fields in front-matter
+    fm_lines = lines[1:end_idx]
+    checksum_line = f"checksum: {checksum}"
+    algorithm_line = f"checksum_algorithm: {algorithm}"
+
+    # Remove existing checksum lines
+    fm_lines = [
+        line
+        for line in fm_lines
+        if not line.startswith("checksum:") and not line.startswith("checksum_algorithm:")
+    ]
+
+    # Add new checksum lines
+    fm_lines.append(checksum_line)
+    fm_lines.append(algorithm_line)
+
+    result = ["---"] + fm_lines + ["---"] + lines[end_idx + 1 :]
+    return "\n".join(result)
+
+
+def reflow_paragraphs(content: str, width: Optional[int] = None) -> str:
+    """Reflow paragraphs to specified width or one sentence per line.
+
+    If width is None or 0, splits into one sentence per line.
+    Otherwise, reflows to the specified width.
+    """
+    lines = content.split("\n")
+    result = []
+    in_code_block = False
+    current_paragraph = []
+
+    for line in lines:
+        # Track code blocks
+        if line.startswith("```"):
+            in_code_block = not in_code_block
+
+        if in_code_block:
+            if current_paragraph:
+                result.extend(_reflow_paragraph(current_paragraph, width))
+                current_paragraph = []
+            result.append(line)
+        elif line.strip() == "":
+            # Empty line marks end of paragraph
+            if current_paragraph:
+                result.extend(_reflow_paragraph(current_paragraph, width))
+                current_paragraph = []
+            result.append("")
+        elif re.match(r"^[#\-\*]", line) or line.startswith(">"):
+            # Heading, list, or blockquote
+            if current_paragraph:
+                result.extend(_reflow_paragraph(current_paragraph, width))
+                current_paragraph = []
+            result.append(line)
+        else:
+            # Regular paragraph line
+            current_paragraph.append(line)
+
+    # Handle remaining paragraph
+    if current_paragraph:
+        result.extend(_reflow_paragraph(current_paragraph, width))
+
+    return "\n".join(result)
+
+
+def _reflow_paragraph(lines: list[str], width: Optional[int] = None) -> list[str]:
+    """Reflow a paragraph (list of lines) to the specified width or sentence per line."""
+    text = " ".join(line.strip() for line in lines if line.strip())
+
+    if width is None or width == 0:
+        # One sentence per line
+        sentences = re.split(r"(?<=[.!?])\s+", text)
+        return [s.strip() for s in sentences if s.strip()]
+    else:
+        # Reflow to width
+        result = []
+        current_line = ""
+        for word in text.split():
+            if not current_line:
+                current_line = word
+            elif len(current_line) + 1 + len(word) <= width:
+                current_line += " " + word
+            else:
+                result.append(current_line)
+                current_line = word
+        if current_line:
+            result.append(current_line)
+        return result