Medical Paper Assistant

🔬 An Auditable MCP Research Workspace for Autonomous and Human-Guided Academic Writing

Core research surfaces: mdpaper 118 full / 12 compact + PubMed 45 + CGU 24 · Managed MCP integrations: 6 (adds Asset-Aware 30 + Draw.io 23 + Zotero Keeper 32) · 38 Skills · 15 Prompt Workflows

📖 繁體中文版 🤖 Auto-Paper: Autonomous + Human-Guided Writing Guide — 13 main gate checkpoints + Phase 2.1 sub-gate, 79 Quality Hooks, Structured Review Loop 🧭 GitHub Pages Wiki — 36 topic pages with Mermaid workflows, SVG architecture maps, full-text search, and dark mode 🚦 Stage-by-stage checks and fixes — plain-language blockers, workflow duties, warnings, repair paths, and human decisions for every code phase

The goal is not one-shot text generation. MedPaper Assistant supports bounded autonomous runs and researcher-led writing through the same observable checkpoints, evidence locators, quality gates, review receipts, and reproducible exports. A solver produces artifacts; independent checks score those artifacts without granting unsupported claims evidence credit.

📦 What's in the Box

This repository is the full authoring and integration workspace behind MedPaper Assistant. It combines the core MCP runtime, the packaged VSIX extension, bundled guides, and pinned integration submodules in one place.

The table above shows the three core research servers. These optional servers complete the six managed MCP integrations (installed via uvx):

• asset-aware (30 tools) — Ingest user-provided DOCX/XLSX/PDF/PPTX source materials and reference full text before drafting
• drawio (23 tools) — CONSORT/PRISMA flowchart generation
• zotero-keeper (32 tools) — Import references from Zotero library

Counts in these tables are release-gated via tool-surface-authority.json and vscode-extension/bundle-manifest.json.

Choose Your Install Surface

The repository is the broader engineering surface. The VSIX is the curated end-user surface.

VSX note: The extension verifies or installs checksum-pinned uv/uvx 0.12.5, then launches the matching core package and all managed external MCPs through isolated, exact SDK 2 sources. A workspace that explicitly defines mdpaper in .vscode/mcp.json remains authoritative and suppresses extension auto-registration. CI smoke covers ubuntu-latest, windows-latest, and macos-14, plus all five exact-archive integrations.

How the Pieces Fit Together

Claude Code, Codex, and OpenClaw

The same evidence and quality gates are available across agent runtimes:

The platform-neutral academic-writing workflow covers manuscripts, proposals, project closeout reports, student papers, preprints, audit gates, and safe exemplar use.

🎯 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 not just a writing assistant. It is a research workspace orchestrator:

• 🔍 Explore First, Decide Later — Browse literature freely, save interesting papers, then decide your research direction
• 📥 Source Material Intake First — Phase 0 scans user-provided DOCX/XLSX/PDF/CSV inputs and flags files that must go through asset-aware ingestion before drafting
• 💬 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.
• The Draw.io MCP server is the pinned Python SDK 2 package in the submodule (or its immutable commit archive). Node.js/npm is needed only for the optional interactive Draw.io web UI, not as an MCP 1 fallback.
• Repository mode launches pinned submodules. Marketplace mode installs exact SDK 2 commit archives for PubMed, CGU, Zotero Keeper, and Draw.io; it never floats to an unverified latest package.
• The frozen Python lock currently resolves the stable MCP SDK 2.1.1 runtime. Source builds of the VSIX and dashboard use the same Node.js 24 baseline as CI; Marketplace users do not need Node.js to run the packaged extension.

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:

Two Workflow Paths

Library Wiki Path

• Create a project with workflow_mode="library-wiki"
• Move through reference_action plus direct save_reference_mcp verified saves → library_action → full-surface wiki materialization when needed
• Use materialize_agent_wiki, Foam graph views, and docs/how-to/llm-wiki.md for cross-note synthesis and traversal

Manuscript Path

• Create a project with workflow_mode="manuscript"
• Move through /mdpaper.search → /mdpaper.concept → /mdpaper.draft → /mdpaper.format
• Only this path enforces concept validation, review loops, and export gates

💡 Recommended usage: converge your literature and concepts in Library Wiki Path first, then switch to Manuscript Path for formal drafting.

Foam + Copilot Knowledge Base

MedPaper already uses Foam as the browse-and-graph layer while Copilot drives ingestion, identity resolution, knowledge-map generation, synthesis pages, block-anchor embeds, and managed graph slices.

The current Foam/Copilot layer now includes orphan / placeholder repair loops, template-driven capture into inbox/, review/, and daily/, richer foam-query dashboards, publish-safe wikilink reference packs under notes/publish/, and project-specific graph_views_json slices.

Docs and tutorials:

• GitHub Pages Wiki
• Formal academic output profiles
• Production academic-writing architecture
• Using the MedPaper LLM Wiki
• Foam Dependency Reference
• Graph-view example for ICU sedation / delirium review

🧠 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)

Representative skill families across the 38 skills:

Project Memory

Each project maintains its own .memory/ folder so the AI can continue previous research coherently. The directory layout now splits by workflow mode:

Manuscript Path

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

Library Wiki Path

projects/{slug}/
├── .memory/
│   ├── activeContext.md   ← Current library/wiki focus and triage state
│   └── progress.md        ← ingest / organize / synthesize milestones
├── concept.md             ← library workspace seed
├── references/            ← materialized reference notes
├── inbox/                 ← raw notes and capture queue
├── concepts/              ← atomic concept pages and backlinks
├── review/                ← graph repair worklists and review notes
├── daily/                 ← templated daily capture pages
└── projects/              ← synthesis pages / workstreams

✨ Key Features

Literature & References

• PubMed + Europe PMC + CORE search (45 search tools)
• PICO parsing for clinical questions
• MCP-to-MCP verified metadata — PMID-based retrieval preserves the source response and trust layer; downstream interpretation still requires evidence checks
• Layered trust: 🔒 VERIFIED (PubMed) · 🤖 AGENT (AI notes) · ✏️ USER (your notes)
• Foam wikilinks: [[author2024_12345678]] with hover preview & backlinks
• Library Wiki Path — inbox/, concepts/, and projects/ note flow with reading queues and cross-note dashboards
• LLM wiki materialization — auto-generated notes/index.md, notes/library/overview.md, context hubs, and draft / figure / table graph notes

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)
• Style and authorship integrity — Evidence-led prose, voice/clarity checks, and disclosure-aware review; never optimized to evade AI detectors

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)
• Content-integrity review — SHA-256/MIME receipts, optional C2PA validation, and a version-pinned remove-ai-watermarks visible/open-DWT detector; the check is offline and detection-only, preserves the original, writes no cleaned derivative, and never treats “not detected” as clean

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
• 16 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 2.x — the legacy 1.x runtime is not supported; tools, prompts, resources, elicitation, and progress notifications use the v2 SDK surface
• Managed Foam graph views — named Default, Evidence, Writing, Assets, and Review graph slices

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                          👤 User Layer                                    │
│  ┌─────────────────┐    ┌──────────────────────────────┐  ┌──────────┐  │
│  │   VS Code        │    │  Foam Extension               │  │Dashboard │  │
│  │   Editor         │    │  [[wikilinks]] autocomplete    │  │(Next.js) │  │
│  │                  │    │  hover preview · backlinks     │  │          │  │
│  └─────────────────┘    └──────────────────────────────┘  └──────────┘  │
└──────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌──────────────────────────────────────────────────────────────────────────┐
│               🤖 Copilot Agent (Orchestrator)                             │
│      38 Skills + 15 Prompt Workflows + Cross-Agent Customization         │
│   /mdpaper.search → /mdpaper.concept → /mdpaper.draft → export          │
└───────┬──────────────────┬──────────────────┬──────────────────┬─────────┘
        │                  │                  │                  │
        ▼                  ▼                  ▼                  ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│ 📝 mdpaper    │  │🔍 pubmed-     │  │💡 cgu         │  │🔌 External    │
│ 118/12 tools  │  │  search       │  │  24 tools     │  │   MCPs (uvx)  │
│               │  │  45 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     │  │               │  │ 📥 asset-aware│
│               │  │               │  │               │  │ • docx/xlsx   │
│               │  │               │  │               │  │ • fulltext    │
└───────┬───────┘  └───────────────┘  └───────────────┘  └───────────────┘
        │
        ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                          💾 Local Storage                                 │
│  projects/{slug}/                                                        │
│  ├── .audit/source-materials.yaml ← Phase 0 scan of user-provided inputs │
│  ├── .audit/exemplar-usage.yaml  ← non-evidentiary exemplar audit        │
│  ├── 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

The mdpaper MCP server exposes 118 (full) / 12 (compact default) tools, plus 3 MCP prompts and 3 MCP resources for official MCP clients.

These counts are runtime-validated via tool-surface-authority.json and scripts/check_tool_surface_authority.py, and the validate/release gates fail if the docs drift from that authority.

Compact mode exposes exactly these 12 stable entrypoints and hides most granular public verbs; set MEDPAPER_TOOL_SURFACE=full to expose the complete surface.

save_reference_mcp(pmid) remains a direct compact safe verb so verified PubMed retrieval cannot be confused with reference_action(action="save_agent"), the lower-trust fallback.

The following tables summarize representative full-surface tools; compact clients reach the same domain capabilities through the entrypoints above.

📁 Project Management

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

📚 Reference Management

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

✍️ Draft & Editing

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

✅ Validation

📊 Data Analysis

🔍 Review & Audit

📄 Export & Submission

🧩 MCP Prompts & Resources

🔍 pubmed-search MCP Tools (45 tools)

💡 CGU Creative Tools (24 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

LLM Wiki Enhancements

• notes/index.md emits live Foam query counts
• registered figures and tables materialize as first-class graph notes
• draft sections plus journal/author/topic/context hubs carry graph-friendly frontmatter
• the library dashboard now exposes overview, queues, concepts, links, and synthesis cross-note views

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, 118 full / 12 compact tools + 3 prompts + 3 resources
│
├── integrations/                  # Bundled MCP servers
│   ├── pubmed-search-mcp/         #   PubMed/PMC/CORE search (45 tools)
│   └── cgu/                       #   Creative generation (24 tools)
│
├── vscode-extension/              # Packaged VSIX surface
│   ├── src/                       #   Extension source
│   ├── bundled/tool/              #   Mirrored Python runtime for marketplace installs
│   ├── skills/                    #   Bundled skill definitions
│   ├── docs/                      #   Bundled Foam / LLM wiki docs
│   └── 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 or library workspace seed
│       ├── references/            #   Local reference library
│       ├── drafts/                #   Markdown drafts (manuscript path)
│       ├── inbox/                 #   Raw notes (library-wiki path)
│       ├── concepts/              #   Atomic concept pages (library-wiki path)
│       ├── projects/              #   Synthesis pages / workstreams (library-wiki path)
│       └── results/               #   Figures, exports
│
├── .agents/skills/                # Codex + OpenClaw repository skills
├── .claude/skills/                # 38 Claude Code / workflow 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, the Code of Conduct, and the private vulnerability-reporting process in SECURITY.md.

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

📚 Citation

If you use Medical Paper Assistant, cite the software release described in CITATION.cff. A BibTeX example is provided for convenience:

@software{medpaperassistant_2026,
  author  = {{MedPaper Assistant contributors}},
  title   = {Medical Paper Assistant},
  year    = {2026},
  version = {1.0.3},
  url     = {https://github.com/u9401066/med-paper-assistant},
  license = {Apache-2.0}
}

Do not cite an unpublished manuscript or invent a DOI. Use the archived release DOI if one is added to CITATION.cff in the future.

📄 License

Apache License 2.0 — See LICENSE