Medical Paper Assistant

🔬 An Integrated AI Toolkit for Medical Paper Writing

3 MCP Servers · ~138 Tools · 26 Skills · 15 Prompt Workflows — All in VS Code

📖 繁體中文版
🤖 Auto-Paper: Fully Autonomous Paper Writing Guide — 11-Phase Pipeline, 78 Quality Hooks, Structured Review Loop

📦 What's in the Box

This is a monorepo toolkit that bundles everything a medical researcher needs — from literature search to Word/LaTeX export — into one integrated VS Code environment.

External MCP Servers (optional, installed via uvx):

• drawio — CONSORT/PRISMA flowchart generation
• zotero-keeper — Import references from Zotero library

VSX note: The MedPaper VS Code extension installs Python MCP tools persistently per machine via uv tool install, attempts uv tool upgrade on later activations, and skips duplicate PubMed Search / Zotero Keeper registration when another installed VS Code extension already provides those MCP servers. CI smoke now covers ubuntu-latest, windows-latest, macos-13, and macos-14, including official MCP client checks plus VSX validation smoke.

How the Pieces Fit Together

flowchart LR
    subgraph IDE["VS Code"]
        Agent["Copilot Agent<br/>26 Skills · 15 Prompts"]
        Foam[Foam Plugin]
        Ext[MedPaper Extension]
        Dash[Dashboard]
    end

    subgraph MCP["MCP Servers (~138 tools)"]
      mdpaper["mdpaper<br/>88 tools + 3 prompts + 3 resources<br/>Draft · Export · Validate · Review"]
        pubmed["pubmed-search<br/>37 tools<br/>Search · Metrics"]
        cgu["CGU<br/>13 tools<br/>Deep Think · Ideas"]
    end

    subgraph Data["Project Data"]
        proj[("projects/{slug}/<br/>· .memory/<br/>· references/<br/>· drafts/")]
    end

    Agent <-->|MCP| mdpaper
    Agent <-->|MCP| pubmed
    Agent <-->|MCP| cgu
    mdpaper -->|HTTP API| pubmed
    Foam <-->|Wikilinks| proj
    mdpaper <--> proj
    Ext --> mdpaper
    Dash --> proj

🎯 Why This Tool?

Traditional paper writing tools require you to know exactly what you want before you start. But research is rarely that linear.

Medical Paper Assistant is different:

• 🔍 Explore First, Decide Later — Browse literature freely, save interesting papers, then decide your research direction
• 💬 Conversational Workflow — Chat naturally with AI to refine your ideas, not fight with forms
• 🧭 Guided Process — Step-by-step prompts guide you from concept to publication-ready manuscript
• 🔗 All-in-One — Search, write, cite, analyze, export — all integrated inside VS Code

🚀 Quick Start

Prerequisites

Install

# Clone with submodules
git clone --recursive https://github.com/u9401066/med-paper-assistant.git
cd med-paper-assistant

# Run setup script
./scripts/setup.sh          # Linux/macOS
.\scripts\setup.ps1         # Windows PowerShell

The script will:

1. ✅ Create Python virtual environment (.venv/)
2. ✅ Initialize pinned Git submodules from this repository
3. ✅ Install all dependencies (via uv)
4. ✅ Create .vscode/mcp.json configuration for mdpaper, pubmed-search, cgu, zotero-keeper, asset-aware, and drawio
5. ✅ Verify MedPaper and CGU startup paths

Important installation notes:

• The setup script uses pinned submodule commits for reproducible installs. It does not auto-track the latest upstream submodule HEAD.
• If you intentionally want newer submodule code, run git submodule update --remote --merge yourself and test before committing.
• drawio uses npx -y @drawio/mcp, so Node.js/npm must be available on the machine.
• zotero-keeper and pubmed-search are launched via uvx in the repo workflow. In the VSX workflow they may be provided either by MedPaper itself or by separate installed VS Code extensions.

Verify: In Copilot Chat, type /mcp — you should see mdpaper listed 🎉

Optional Integrations

# Foam for reference linking (highly recommended)
code --install-extension foam.foam-vscode

# Draw.io for diagram generation
./scripts/setup-integrations.sh && ./scripts/start-drawio.sh

Windows PowerShell:

.\scripts\setup-integrations.ps1
.\scripts\start-drawio.ps1

💬 MCP Prompts — Just Type and Go

In Copilot Chat, type these prompts to trigger guided workflows:

💡 Recommended Workflow: /mdpaper.search → /mdpaper.concept → /mdpaper.draft → /mdpaper.format

🧠 Skill System + Project Memory

Our core differentiator: We don't just provide tools — we provide guided workflows that know how to combine tools effectively, AND project memory that remembers your research journey across sessions.

What is a Skill?

Tool  = Single capability (search, save, analyze...)
Skill = Complete knowledge (how to combine tools to accomplish tasks)

26 Skills covering the full research lifecycle:

Project Memory

Each project maintains its own .memory/ folder, so the AI continues previous research coherently:

projects/{slug}/
├── .memory/
│   ├── activeContext.md   ← Agent's working memory
│   └── progress.md        ← Research milestones
├── concept.md             ← Research concept (with 🔒 protected sections)
├── references/            ← Foam-compatible literature library
├── drafts/                ← Markdown drafts with [[citations]]
├── data/                  ← CSV data files
└── results/               ← Figures, .docx exports

✨ Key Features

Literature & References

• PubMed + Europe PMC + CORE search (37 search tools)
• PICO parsing for clinical questions
• MCP-to-MCP verified data — PMID sent directly, no agent hallucination
• Layered trust: 🔒 VERIFIED (PubMed) · 🤖 AGENT (AI notes) · ✏️ USER (your notes)
• Foam wikilinks: [[author2024_12345678]] with hover preview & backlinks

Writing & Editing

• AI draft generation per section (Introduction, Methods, Results, Discussion)
• Citation-Aware Editing — patch_draft validates all [[wikilinks]] before saving
• Auto-fix citation format — [[12345678]] → [[author2024_12345678]]
• Novelty validation — 3-round independent scoring (threshold: 75/100)
• Anti-AI writing rules — Evidence funnel structure, no clichés

Data Analysis

• CSV dataset analysis with descriptive statistics
• Statistical tests (t-test, ANOVA, chi², correlation, Mann-Whitney, Fisher's)
• Table 1 generator — Baseline characteristics with automatic variable detection
• Publication-ready figures (matplotlib/seaborn)

Export & Submission

• Word export with journal template support
• Cover letter + highlights generation
• Manuscript consistency checker
• Reviewer response generator (point-by-point format)
• Submission checklist (word count, figure format, etc.)

Infrastructure

• DDD Architecture (Domain-Driven Design) with clean layer separation
• 15 pre-commit hooks (ruff, mypy, bandit, pytest, prettier, doc-update...)
• Workspace State recovery for cross-session continuity
• uv for all Python package management
• MCP SDK features in active use — tools, elicitation, and progress notifications for long-running audit/review operations

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                          👤 User Layer                                    │
│  ┌─────────────────┐    ┌──────────────────────────────┐  ┌──────────┐  │
│  │   VS Code        │    │  Foam Extension               │  │Dashboard │  │
│  │   Editor         │    │  [[wikilinks]] autocomplete    │  │(Next.js) │  │
│  │                  │    │  hover preview · backlinks     │  │          │  │
│  └─────────────────┘    └──────────────────────────────┘  └──────────┘  │
└──────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌──────────────────────────────────────────────────────────────────────────┐
│               🤖 Copilot Agent (Orchestrator)                             │
│      26 Skills + 15 Prompt Workflows + Agent Customization               │
│   /mdpaper.search → /mdpaper.concept → /mdpaper.draft → export          │
└───────┬──────────────────┬──────────────────┬──────────────────┬─────────┘
        │                  │                  │                  │
        ▼                  ▼                  ▼                  ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│ 📝 mdpaper    │  │🔍 pubmed-     │  │💡 cgu         │  │🔌 External    │
│  88 tools     │  │  search       │  │  13 tools     │  │   MCPs (uvx)  │
│               │  │  37 tools     │  │               │  │               │
│ • projects    │  │ • PubMed      │  │ • brainstorm  │  │ 🎨 drawio     │
│ • references  │  │ • Europe PMC  │  │ • deep_think  │  │ • diagrams    │
│ • drafts      │  │ • CORE        │  │ • spark       │  │               │
│ • validation  │  │ • PICO        │  │ • methods     │  │ 📖 zotero     │
│ • analysis    │  │ • Gene/Chem   │  │               │  │ • import refs │
│ • export      │  │ • Session     │  │               │  │               │
└───────┬───────┘  └───────────────┘  └───────────────┘  └───────────────┘
        │
        ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                          💾 Local Storage                                 │
│  projects/{slug}/                                                        │
│  ├── concept.md          ← Research concept with 🔒 protected sections   │
│  ├── references/{pmid}/  ← Foam-compatible .md + metadata.json           │
│  ├── drafts/             ← Markdown drafts with [[citations]]            │
│  ├── data/               ← CSV data files                                │
│  └── results/            ← Figures, .docx exports                        │
└──────────────────────────────────────────────────────────────────────────┘

MCP-to-MCP Direct Communication

When saving references, data flows directly between MCP servers — the Agent only passes a PMID, never full metadata:

Agent: "save PMID:24891204"
     │
     ▼
mdpaper.save_reference_mcp(pmid="24891204")
     │  Direct HTTP call (not through Agent)
     ▼
pubmed-search: GET /api/cached_article/24891204
     │  Returns verified PubMed data
     ▼
Saved with layered trust:
  🔒 VERIFIED: PubMed data (immutable)
  🤖 AGENT:    AI notes (marked source)
  ✏️ USER:     Your notes (editable)

🛠️ mdpaper MCP Tools

88 active tools organized into 7 groups, plus 3 MCP prompts and 3 MCP resources for official MCP clients.

📁 Project Management (17 tools)

Projects, exploration mode, workspace state recovery, diagram management.

📚 Reference Management (12 tools)

Save, search, format, and manage references with Foam integration.

✍️ Draft & Editing (13 tools)

Write, edit, cite — with built-in validation.

✅ Validation (3 tools)

📊 Data Analysis (10 tools)

🔍 Review & Audit (23 tools)

📄 Export & Submission (10 tools)

🧩 MCP Prompts & Resources

🔍 pubmed-search MCP Tools (37 tools)

💡 CGU Creative Tools (13 tools)

CGU runtime notes:

• In the repository workflow, CGU is started from the pinned submodule with uv run --directory integrations/cgu python -m cgu.server.
• In the VSX workflow, MedPaper registers CGU when bundled code or the workspace submodule is available; otherwise CGU is simply skipped.
• CGU itself supports Python >=3.11, but this repository currently requires Python >=3.12, so cross-platform repo setup should be treated as Python 3.12 baseline on macOS, Linux, and Windows.
• The default repo MCP example uses CGU_THINKING_ENGINE=simple, which is the low-friction mode. Advanced LLM-backed modes still depend on CGU-side model/provider configuration.

🔗 Foam Integration

Citation Autocomplete

Type [[ in any draft to trigger the autocomplete menu:

According to previous studies [[    ← Type [[ here
                              ┌─────────────────────────────┐
                              │ 🔍 greer2017_27345583       │
                              │    smith2020_12345678       │
                              │    chen2019_87654321        │
                              └─────────────────────────────┘

Search by author ([[greer), year ([[2017), PMID ([[27345583), or keyword ([[sedation).

📚 Reference File Structure

References are stored with Foam-optimized, layered-trust structure:

references/{pmid}/
├── {citation_key}.md   ← YAML frontmatter + abstract (human-readable)
└── metadata.json       ← Full metadata (programmatic access)

---
# 🔒 VERIFIED (from PubMed, immutable)
title: "Complications of airway management"
author:
  - { family: Pacheco-Lopez, given: Paulette C }
year: 2014
journal: Respiratory Care
pmid: "24891204"
_source:
  mcp: pubmed-search
  verified: true

# 🤖 AGENT (AI-generated, marked)
_agent:
  notes: "Key review on airway complications"
  relevance: high

# Foam
aliases: [pachecolopez2014, "PMID:24891204"]
tags: [reference, airway, review]
---

📂 Project Structure

med-paper-assistant/
├── src/med_paper_assistant/       # Core MCP server (DDD architecture)
│   ├── domain/                    #   Business logic, entities, value objects
│   ├── application/               #   Use cases, services
│   ├── infrastructure/            #   DAL, external services
│   └── interfaces/mcp/            #   MCP server, 88 tools + 3 prompts + 3 resources
│
├── integrations/                  # Bundled MCP servers
│   ├── pubmed-search-mcp/         #   PubMed/PMC/CORE search (37 tools)
│   └── cgu/                       #   Creative generation (13 tools)
│
├── vscode-extension/              # VS Code Extension
│   ├── src/                       #   Extension source
│   ├── skills/                    #   Agent skill definitions
│   └── prompts/                   #   Quick-action prompts
│
├── dashboard/                     # Next.js project management UI
│   └── src/
│
├── projects/                      # Research projects (isolated workspaces)
│   └── {slug}/
│       ├── .memory/               #   Cross-session AI memory
│       ├── concept.md             #   Research concept
│       ├── references/            #   Local reference library
│       ├── drafts/                #   Markdown drafts
│       └── results/               #   Figures, exports
│
├── .claude/skills/                # 26 Agent skill definitions
├── .github/prompts/               # 15 Prompt workflow files
├── templates/                     # Journal Word templates
├── memory-bank/                   # Global project memory
└── tests/                         # pytest test suite

🗺️ Roadmap

Architecture Direction: Direction C — Full VSX + Foam + Pandoc

Legend: ✅ Complete | 🔜 In Progress | 📋 Planned

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

• 🐛 Report bugs — Open an issue
• 💡 Suggest features — Share your ideas
• 🔧 Submit code — Fork → Branch → PR

� Citation

If you use Medical Paper Assistant in your research, please cite our paper:

@article{medpaper2025,
  title   = {MedPaper Assistant: A Self-Evolving, MCP-Based Framework for
             AI-Assisted Medical Paper Writing with Closed-Loop Quality Assurance},
  author  = {[Authors]},
  year    = {2025},
  note    = {Submitted to medRxiv},
  url     = {https://github.com/u9401066/med-paper-assistant}
}

Note: This paper was produced entirely by the MedPaper Assistant's autonomous pipeline as a self-referential demonstration. The manuscript, audit trail, and all quality metrics are available in projects/self-evolving-ai-paper-writing-framework/. The preprint is being submitted to medRxiv — this section will be updated with the DOI once available.

�📄 License

Apache License 2.0 — See LICENSE