Med Paper Assistant

Medical Paper Assistant

[](https://www.python.org/downloads/) [](https://modelcontextprotocol.io/) [](https://github.com/features/copilot) [](https://github.com/u9401066/med-paper-assistant)

🔬 An MCP-Orchestrated Research Workspace for Medical Paper Writing and LLM Wiki Workflows

3 MCP Servers · 188+ Tools · 26 Skills · 15 Prompts Workflows — monorepo authoring surface plus packaged VSIX surface in one VS Code ecosystem

> 📖 [繁體中文版](README.zh-TW.md) > 🤖 [Auto-Paper: Fully Autonomous Paper Writing Guide](docs/auto-paper-guide.md) — 13 main gate checkpoints + Phase 2.1 sub-gate, 79 Quality Hooks, Structured Review Loop

---

📦 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.

| Component | Type | Tools | Description | | ------------------------------------------------------------------ | ---------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | mdpaper | Core MCP Server | 118 (full) / 22 (compact default) | Dual workflow server for manuscript and library-wiki paths, plus 3 MCP prompts and 3 MCP resources | | pubmed-search | MCP Server (submodule) | 46 | PubMed/Europe PMC/CORE search, PICO, citation metrics, session mgmt | | CGU | MCP Server (submodule) | 24 | Creative generation: brainstorm, deep think, spark collision | | [VS Code Extension](vscode-extension/) | Extension | 11 cmds + 10 chat | MCP auto-registration, compact-first packaged surface, workspace setup, LLM wiki guide, Foam graph views, @mdpaper chat participant | | [Dashboard](dashboard/) | Next.js Web App | — | Project management UI, diagram editor | | Foam | VS Code Extension | — | [[wikilink]] citation linking, hover preview, graph view | | [Skills](.claude/skills/) | Agent Workflows | 26 | Guided multi-tool workflows (literature review, draft writing...) | | [Prompts](.github/prompts/) | Prompt Files | 15 | /mdpaper.search, /mdpaper.draft, etc. |

External MCP Servers (optional, installed via uvx):

• asset-aware — Ingest user-provided DOCX/XLSX/PDF/PPTX source materials and reference full text before drafting
• drawio — CONSORT/PRISMA flowchart generation
• zotero-keeper — 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

| Surface | Best for | What you get | | ------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Full repository | Maintainers, power users, and workflow authors | Core mdpaper runtime, pinned MCP integrations/submodules, 26 skills, 15 prompt workflows, repo scripts, tests, and authoring docs | | VSIX extension | End users who want the packaged experience | @mdpaper, 11 palette commands, compact-first mdpaper runtime (22 tools by default / 118 optional), 14 bundled skills, 13 bundled prompt workflows, 9 bundled agents, and bundled LLM wiki docs |

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

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, and macos-14, including official MCP client checks plus VSX validation smoke.

How the Pieces Fit Together

---

🎯 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

| Traditional Tools | Medical Paper Assistant | | ----------------------------------- | ------------------------------------------------------------------------ | | Fixed templates, rigid workflow | Flexible, exploratory approach | | Separate apps for search/write/cite | One orchestrated workspace: 188+ tools and packaged workflows in VS Code | | Manual reference management | Auto-save with verified PubMed data | | Export then format | Direct Word export with journal styles | | Learn complex UI | Natural language conversation |

---

🚀 Quick Start

Prerequisites

| Requirement | Version | Check | | ------------------ | ---------- | ------------------- | | Python | 3.12+ | python3 --version | | Git | Any recent | git --version | | VS Code | Latest | Help → About | | GitHub Copilot | Extension | Extensions panel |

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:

| Prompt | Description | | ------------------- | --------------------------------------------------- | | /mdpaper.search | 🔍 Start here! Explore literature, save papers | | /mdpaper.concept | 📝 Develop research concept with novelty validation | | /mdpaper.draft | ✍️ Write manuscript with auto-citations | | /mdpaper.analysis | 📊 Analyze CSV data, generate figures & Table 1 | | /mdpaper.format | 📄 Export to Word with journal formatting | | /mdpaper.clarify | 🔄 Refine specific sections through conversation | | /mdpaper.project | 📁 Create or switch research projects | | /mdpaper.strategy | ⚙️ Configure search strategy (dates, filters) | | /mdpaper.help | ❓ Show all available commands |

Two Workflow Paths

Library Wiki Path

• Create a project with workflow_mode="library-wiki"
• Move through search/save_reference_mcp → write_library_note / move_library_note → show_reading_queues / build_library_dashboard
• 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:

• [Using the MedPaper LLM Wiki](docs/how-to/llm-wiki.md)
• [Foam Dependency Reference](docs/reference/foam.md)
• [Graph-view example for ICU sedation / delirium review](docs/how-to/llm-wiki.md)

---

🧠 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 26 skills:

| Category | Skills | Triggers | | -------------- | ----------------------------------------------------------------------------------- | ----------------------------------------- | | 🔬 Research | literature-review, concept-development, concept-validation, parallel-search | "找論文", "search", "concept", "validate" | | ✍️ Writing | draft-writing, reference-management, word-export | "寫草稿", "draft", "citation", "export" | | 📁 Management | project-management, memory-updater, memory-checkpoint | "新專案", "切換", "存檔" | | 🛠️ Development | git-precommit, code-refactor, test-generator, code-reviewer | "commit", "refactor", "test" |

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 (46 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
• 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)
• 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.)

Infrastru

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: u9401066
• Source: u9401066/med-paper-assistant
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.