MCP Academic Editor

Surgical manuscript editing with word count protection via Model Context Protocol

A sophisticated academic manuscript revision system that provides surgical, line-anchored editing tools through the Model Context Protocol (MCP). Designed specifically for researchers who need precise manuscript revisions while maintaining word count requirements and semantic integrity.

Best for workflows like this:

1. You receive comments from editor that can easily be resolved by: a) small edits in wording b) direct specific information provided in comments, c) organizational issues
2. Use our J-Reviewer MCP (or a similar tool) which reviews your article then provides measured critiques
3. Then have J-Reviewer propose surgical edits to address issues
4. Produce a patch, .diff or a full comment list that specifically addresses the issues
5. Apply patch and review bolded edits (bolded-edits coming soon)

Not good for:

1. Issues that are open ended with no clear answer
2. Ambiguous critique
3. Issues that require intensive extra research

🔒 Critical Safety Features

Word Count Protection Guarantee: This system will NEVER reduce your manuscript below 95% of its original word count. All edits are designed to augment and enhance your work, not replace or delete content.

• ✅ Augmentation Mode: Prefers additions over replacements
• ✅ Word Count Verification: Blocks edits that would reduce word count significantly
• ✅ Emergency Recovery: Built-in backup and recovery mechanisms
• ✅ Semantic Preservation: Maintains your core thesis and claims
• ✅ Journal Compliance: Enforces minimum word count requirements (configurable, default 8000)

🚀 Key Features

Intelligent Document Processing

• Universal Format Support: Markdown (.md), Word (.docx), LaTeX (.tex), and PDF
• Automatic Structure Detection: Identifies sections, paragraphs, and citation patterns
• Comment Integration: Processes reviewer comments from any format (plain text, JSON, files)

Surgical Editing Engine

• Line-Anchored Diffs: Precise edits that preserve document structure
• Conflict Resolution: Handles overlapping edit suggestions intelligently
• Span-Based Reconstruction: Maintains formatting and cross-references

Semantic Safety

• Vision Brief Integration: Preserves your core thesis and key claims
• Protected Sections: Mark sections as untouchable during revision
• Verification Pipeline: Multi-layer checks before applying any changes

Core Philosophy

• Thesis Preservation: Never compromise the core argument
• Surgical Precision: Make minimal, targeted changes
• Semantic Awareness: Understand meaning, not just text
• Reviewer Integration: Handle feedback in any format
• Conflict Resolution: Detect and resolve competing edits

Key Features

🎯 Surgical Line-Anchored Editing

• Precise targeting of specific manuscript sections
• Line-level granularity for exact placement
• Conflict detection between overlapping edits
• Semantic verification of changes

📝 Universal Comment Parsing

Handles reviewer comments in any format:

• JSON structured data
• Plain text feedback
• Diff-style suggestions
• Markdown formatted reviews
• PDF annotations (via text extraction)
• Word document comments
• Lists of comment strings
• Raw text with embedded feedback

🧠 Semantic Preservation

• Natural Language Inference (NLI) verification
• Meaning preservation checks
• Thesis alignment validation
• Argument structure maintenance

⚡ Six-Stage Pipeline

1. Ingest - Parse manuscript and comments
2. Align - Match comments to manuscript locations
3. Plan - Generate edit strategies
4. Patch - Apply surgical modifications
5. Verify - Ensure semantic consistency
6. Assemble - Produce final manuscript

📦 Installation

Requirements

• Python 3.9+
• MCP-compatible client (Claude Desktop recommended)

Quick Install

git clone https://github.com/drquandary/mcp-academic-editor.git
cd mcp-academic-editor
pip install -r requirements.txt

Development Install

pip install -e ".[dev]"

🔧 Configuration

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "academic-editor": {
      "command": "/path/to/your/python3",
      "args": ["/path/to/mcp-academic-editor/server.py"],
      "env": {
        "PYTHONPATH": "/path/to/mcp-academic-editor"
      }
    }
  }
}

Important: Use the full path to Python where MCP packages are installed:

• If using conda: /Users/username/miniconda3/bin/python3
• If using system Python with pip: /usr/local/bin/python3
• Find your path with: which python3

Standalone Usage

python3 server.py

🎯 Usage Examples

Basic Manuscript Processing

# Through MCP tools in Claude Desktop
process_manuscript(
    manuscript_path="/path/to/paper.md",
    comments_source="reviewer_comments.txt",
    vision_thesis="AI therapy creates new forms of care",
    vision_claims=[
        "Modal literacy is measurable",
        "Therapeutic encounters are embodied", 
        "AI systems participate in care practices"
    ]
)

Safe Surgical Editing

# Preview edits first (recommended)
preview_surgical_edits(
    comments_source="additional_comments.json",
    max_preview=10
)

# Apply edits with safety guarantees
apply_surgical_edits(
    output_directory="revision_2024",
    apply_edits=True,
    generate_report=True
)

Emergency Recovery

# If something goes wrong, restore from backup
python3 scripts/emergency_recovery.py

Flexible Comment Input

The system accepts comments in any format:

# From file
editor.process_manuscript("paper.md", "comments.json")

# From text string  
editor.process_manuscript("paper.md", "Please clarify the methodology...")

# From list
comments = [
    "Add more citations in introduction",
    "Figure 2 needs better caption", 
    "Conclusion too brief"
]
editor.process_manuscript("paper.md", comments)

# From diff format
diff_feedback = """
@@ -45,7 +45,7 @@
-The sample was adequate
+The sample (n=150) was adequate for 80% power
"""
editor.process_manuscript("paper.md", diff_feedback)

🛠 Available MCP Tools

1. process_manuscript

Purpose: Load and analyze academic manuscripts

• Supports multiple formats (.md, .docx, .tex, .pdf)
• Auto-detects structure and sections
• Integrates vision brief for semantic preservation

2. parse_comments

Purpose: Process reviewer comments from any source

• Plain text, JSON, files, or lists
• Auto-detects comment types (clarify, add_citation, restructure, etc.)
• Assigns priority levels automatically

3. get_manuscript_structure

Purpose: Analyze document organization

• Section mapping and span analysis
• Protected content identification
• Paragraph and heading structure

4. create_vision_brief

Purpose: Define revision constraints and goals

• Core thesis preservation
• Key claims protection
• Section-level protection rules

5. analyze_comment_alignment

Purpose: Match comments to manuscript sections

• Keyword-based section detection
• Confidence scoring for alignments
• Manual review flagging

6. preview_surgical_edits

Purpose: Preview changes before applying

• Safe edit filtering
• Semantic similarity scoring
• Word count impact analysis

7. apply_surgical_edits

Purpose: Execute manuscript revisions

• Multi-layer safety verification
• Word count protection enforcement
• Detailed revision reporting

8. get_comment_types_info

Purpose: Reference for comment classification

• Available comment types and meanings
• Priority level definitions
• Usage guidelines

🧠 Core Components

Document Ingestor (src/ingest.py)

• Multi-format document parsing
• Structure extraction and span creation
• Comment parsing from various sources

Edit Planner (src/plan.py)

• Comment-to-edit translation
• Operation type determination (expand, insert_after, replace)
• Safety Feature: Defaults to augmentation operations

Surgical Editor (src/patch.py)

• Line-anchored diff application
• Conflict detection and resolution
• Safety Feature: Word count verification before applying

Semantic Verifier (src/verify.py)

• Thesis and claim preservation checking
• Semantic similarity analysis
• Safety Feature: Minimum word count enforcement

Revision Assembler (src/assemble.py)

• Content reconstruction with original preservation
• Report generation
• Safety Feature: Fallback to original content if issues detected

⚙️ Configuration Options

Word Count Protection

config = {
    "preserve_word_count": True,           # Enable word count protection
    "minimum_word_count_ratio": 0.95,      # Don't reduce by more than 5%
    "augment_only_mode": True,             # Only allow additions
    "minimum_total_words": 8000,           # Journal requirement
    "enforce_growth_only": True            # Safer for academic papers
}

Edit Operations

config = {
    "preserve_formatting": True,           # Maintain document structure
    "verify_before_apply": True,           # Multi-layer verification
    "backup_original": True,               # Create safety backups
    "generate_report": True                # Detailed change reports
}

📊 Example Workflow

1. Initial Processing

# Load your manuscript and reviewer comments
process_manuscript(
    manuscript_path="my_paper.md",
    comments_source="reviews.txt", 
    vision_thesis="Your core argument here"
)

2. Analysis

# Check manuscript structure
get_manuscript_structure()

# Analyze comment alignment  
analyze_comment_alignment()

3. Safe Editing

# Preview changes first
preview_surgical_edits(max_preview=5)

# Apply with full safety checks
apply_surgical_edits(
    apply_edits=True,
    output_directory="final_revision"
)

Architecture

Data Models

• Manuscript: Structured document with semantic spans
• Comment: Reviewer feedback with type classification
• VisionBrief: Core thesis and constraints
• UnifiedDiff: Line-anchored edit operations

Comment Types

• CLARIFY - Requests for explanation
• ADD_CITATION - Source/reference needs
• RESTRUCTURE - Organizational changes
• TIGHTEN - Concision improvements
• COUNTERARGUMENT - Address opposing views
• COPYEDIT - Grammar/style fixes
• EVIDENCE_GAP - Missing support

Processing Pipeline

📄 Manuscript + 💬 Comments → 🎯 Surgical Edits → 📄 Revised Manuscript
     ↓                           ↓                        ↑
  [INGEST]                   [PATCH]                 [ASSEMBLE]
     ↓                           ↑                        ↑  
  [ALIGN] ←---------------→ [PLAN] ←------------→ [VERIFY]

Configuration

config/default.yaml

# Parsing settings
preserve_formatting: true
auto_detect_format: true
extract_quoted_text: true
infer_comment_types: true

# Alignment settings  
use_embeddings: true
similarity_threshold: 0.75
keyword_weight: 0.3
context_window: 3

# Planning settings
max_edits_per_span: 3
preserve_protected_spans: true
conflict_resolution: "prioritize_high"

# Verification settings
enable_nli_checking: true
semantic_similarity_threshold: 0.8
preserve_thesis: true

Advanced Features

Conflict Resolution

When multiple edits target the same text:

# Automatic conflict detection
conflicts = editor.detect_conflicts(planned_edits)

# Resolution strategies
editor.resolve_conflicts(conflicts, strategy="prioritize_high")

Semantic Verification

# Check if edits preserve meaning
verification = editor.verify_edits(original_spans, modified_spans)
if not verification.thesis_preserved:
    editor.rollback_problematic_edits()

Interactive Review

# Review edits before applying
editor.interactive_review_mode = True
result = editor.process_manuscript(manuscript, comments)
# Prompts for approval of each edit

Example Workflows

Standard Academic Revision

# Process peer review feedback
vision = VisionBrief(
    thesis="Your core argument here",
    claims=["Key claim 1", "Key claim 2"],
    do_not_change=["Methodology", "Results"]
)

editor = AcademicEditor()
result = editor.process_manuscript(
    "draft.md", 
    "peer_review.pdf",  # Automatically extracts comments
    vision
)

print(f"Applied {len(result.applied_edits)} surgical edits")
print(f"Preserved thesis: {result.verification.thesis_preserved}")

Multi-Reviewer Integration

# Handle multiple reviewer files
reviewer_sources = [
    "reviewer1_comments.docx",
    "reviewer2_feedback.txt", 
    "reviewer3_suggestions.json"
]

for source in reviewer_sources:
    result = editor.process_manuscript("manuscript.md", source, vision)
    editor.merge_results(result)

Diff-Style Editing

# Process git-style diffs
diff_comments = """
@@ -120,3 +120,5 @@ methodology section
 The analysis followed standard procedures.
+However, we acknowledge limitations in sample diversity.
+Future work should address these constraints.
"""

result = editor.process_manuscript("paper.md", diff_comments, vision)

🔍 Troubleshooting

Word Count Issues

If you experience word count reduction:

1. Check Safety Settings: Ensure augment_only_mode: true
2. Use Emergency Recovery: Run scripts/emergency_recovery.py
3. Review Operation Types: Verify edits use "expand" not "replace"

Claude Desktop Connection Issues

# Test the MCP server
python3 scripts/test_mcp_connection.py

# Validate configuration
python3 tests/test_mcp_connection.py

Import Errors

# Ensure PYTHONPATH is set correctly
export PYTHONPATH="/path/to/mcp-academic-editor:$PYTHONPATH"

Python Path Issues

If you see ModuleNotFoundError: No module named 'mcp':

1. Check your Python installation:

   which python3
   python3 -c "import mcp; print('MCP installed')"
   

2. Update Claude Desktop config with the correct Python path:

   "command": "/full/path/to/python3"
   

3. Install MCP in the right environment:

   # If using conda
   conda install -c conda-forge mcp
   
   # If using pip
   pip install mcp fastmcp
   

🧪 Testing

Run Test Suite

pytest tests/ -v

Test MCP Connection

python3 tests/test_mcp_connection.py

Manual Testing

# Test with sample files
python3 test_flexible_parsing.py

Expected output:

Testing Flexible Comment Parsing System
==================================================
Testing JSON comments...
Parsed 2 comments from JSON string
Testing plain text comments...  
Parsed 1 comments from plain text
Testing diff-style comments...
Parsed 1 comments from diff format
Testing list of comments...
Parsed 4 comments from list
Testing markdown comments...
Parsed 2 comments from markdown
==================================================
All tests completed successfully!
The system can handle comments 'however they are given'

📚 Academic Context

This system was developed for researchers working on complex academic manuscripts that require:

• Journal Compliance: Meeting specific word count requirements
• Reviewer Response: Systematic addressing of peer review comments
• Thesis Preservation: Maintaining core arguments during revision
• Citation Integrity: Preserving reference accuracy and formatting

Supported Academic Workflows

• Manuscript revision for journal submission
• Response to peer reviewer comments
• Collaborative editing with supervisors
• Multi-round revision cycles
• Emergency manuscript recovery

Use Cases

Academic Researchers

• Revise papers based on peer review
• Maintain thesis integrity during revision
• Handle multi-reviewer feedback efficiently
• Preserve methodological sections

Journal Editors

• Assist authors with revision guidance
• Standardize feedback processing
• Ensure consistent editorial quality
• Track revision compliance

Graduate Students

• Learn surgical editing techniques
• Process advisor feedback systematically
• Maintain argument coherence
• Handle complex revision requirements

🤝 Contributing

Development Setup

git clone https://github.com/drquandary/mcp-academic-editor.git
cd mcp-academic-editor
pip install -e ".[dev]"
pre-commit install

Code Style

• Black formatting
• isort import sorting
• mypy type checking
• pytest testing

Pull Requests

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'feat: add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📋 Changelog

v1.0.0 (2024)

• ✅ CRITICAL FIX: Word count protection system
• ✅ NEW: Augmentation-only editing mode
• ✅ NEW: Emergency recovery scripts
• ✅ NEW: Semantic preservation verification
• ✅ NEW: Claude Desktop integration
• ✅ NEW: Multi-format document support

⚖️ License

MIT License - see LICENSE file for details.

🆘 Support

Emergency Issues

If the system has damaged your manuscript:

1. Immediate: Run scripts/emergency_recovery.py
2. Backup: Check for auto-created backup files
3. Contact: Create GitHub issue with "URGENT" label

General Support

• 📖 Documentation: See docs/ directory
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Contact: [Your contact information]

🙏 Acknowledgments

Developed for researchers who need sophisticated manuscript revision tools without risking their work. Special thanks to the academic community for testing and feedback that led to the critical safety features.

Citation

If you use this system in academic work, please cite:

@software{mcp_academic_editor,
  title={MCP Academic Editor: Surgical Manuscript Editing with Word Count Protection},
  author={Jeffrey Vadala},
  year={2024},
  url={https://github.com/drquandary/mcp-academic-editor}
}

---

⚠️ Safety Guarantee: This system is designed to enhance your academic manuscripts, never to reduce or damage them. All edits are reversible and word count is actively protected.

"Handle comments however they are given, preserve thesis however it matters."