Skip to main content

An MCP-orchestrated research workspace for manuscript and library-wiki workflows

Project description

Medical Paper Assistant

Python MCP Copilot License

Windows Linux macOS

๐Ÿ”ฌ An MCP-Orchestrated Research Workspace for Medical Paper Writing and LLM Wiki Workflows

3 MCP Servers ยท 165+ Tools ยท 26 Skills ยท 15 Prompts Workflows โ€” monorepo authoring surface plus packaged VSIX surface in one VS Code ecosystem

๐Ÿ“– ็น้ซ”ไธญๆ–‡็‰ˆ ๐Ÿค– Auto-Paper: Fully Autonomous Paper Writing Guide โ€” 11-Phase Pipeline, 79 Quality Hooks, Structured Review Loop

MedPaper Assistant overview


๐Ÿ“ฆ 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 117 (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) 37 PubMed/Europe PMC/CORE search, PICO, citation metrics, session mgmt
CGU MCP Server (submodule) 13 Creative generation: brainstorm, deep think, spark collision
VS Code 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 Next.js Web App โ€” Project management UI, diagram editor
Foam VS Code Extension โ€” [[wikilink]] citation linking, hover preview, graph view
Skills Agent Workflows 26 Guided multi-tool workflows (literature review, draft writing...)
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 / 117 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, macos-13, and macos-14, including official MCP client checks plus VSX validation smoke.

How the Pieces Fit Together

MedPaper Assistant architecture


๐ŸŽฏ 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: 165+ 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:


๐Ÿง  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 (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
  • 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.)

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 features in active use โ€” tools, elicitation, and progress notifications for long-running audit/review operations
  • 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)                             โ”‚
โ”‚      26 Skills + 15 Prompt Workflows + Agent Customization               โ”‚
โ”‚   /mdpaper.search โ†’ /mdpaper.concept โ†’ /mdpaper.draft โ†’ export          โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
        โ”‚                  โ”‚                  โ”‚                  โ”‚
        โ–ผ                  โ–ผ                  โ–ผ                  โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ ๐Ÿ“ mdpaper    โ”‚  โ”‚๐Ÿ” pubmed-     โ”‚  โ”‚๐Ÿ’ก cgu         โ”‚  โ”‚๐Ÿ”Œ External    โ”‚
โ”‚ 117/22 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     โ”‚  โ”‚               โ”‚  โ”‚ ๐Ÿ“ฅ asset-awareโ”‚
โ”‚               โ”‚  โ”‚               โ”‚  โ”‚               โ”‚  โ”‚ โ€ข docx/xlsx   โ”‚
โ”‚               โ”‚  โ”‚               โ”‚  โ”‚               โ”‚  โ”‚ โ€ข fulltext    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
        โ”‚
        โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                          ๐Ÿ’พ Local Storage                                 โ”‚
โ”‚  projects/{slug}/                                                        โ”‚
โ”‚  โ”œโ”€โ”€ .audit/source-materials.yaml โ† Phase 0 scan of user-provided inputs โ”‚
โ”‚  โ”œโ”€โ”€ 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

115 tools (full surface) / 22 tools (compact default), 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 keeps the main facade entrypoints (project/workspace/review/pipeline/export) and hides most granular public verbs; set MEDPAPER_TOOL_SURFACE=full to expose the complete surface.

๐Ÿ“ Project Management

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

Key Tools Description
create_project / switch_project / delete_project Project lifecycle
start_exploration / convert_exploration_to_project Explore-first workflow
get_workspace_state / sync_workspace_state Cross-session recovery
save_diagram / list_diagrams Draw.io integration
setup_project_interactive Interactive paper type configuration
update_authors Manage structured author metadata

๐Ÿ“š Reference Management

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

Key Tools Description
save_reference_mcp Recommended โ€” Save by PMID via MCP-to-MCP (verified data)
list_saved_references / search_local_references Browse & search library
format_references / set_citation_style Vancouver / APA / Nature
sync_references Sync [[wikilinks]] to numbered references

โœ๏ธ Draft & Editing

Write, edit, cite โ€” with built-in validation.

Key Tools Description
draft_section / write_draft Create and write sections
list_drafts / read_draft / delete_draft Draft lifecycle
get_available_citations List all valid [[citation_key]] before editing
patch_draft Citation-aware partial edit with wikilink validation
insert_citation / suggest_citations Smart citation insertion
scan_draft_citations / sync_references Citation management
count_words Section and manuscript word-count checks

โœ… Validation

Tool Description
validate_concept Full novelty scoring against the active concept
validate_wikilinks Auto-fix [[12345678]] โ†’ [[author2024_12345678]]
compare_with_literature Compare the current idea against saved references

๐Ÿ“Š Data Analysis

Tool Description
analyze_dataset Descriptive statistics for CSV
run_statistical_test t-test, ANOVA, chiยฒ, correlation, etc.
generate_table_one Baseline characteristics with auto variable detection
create_plot Publication-ready figures
insert_figure Insert figure into draft with archive validation
insert_table Insert table into draft with archive validation
list_assets List figures and tables in project results

๐Ÿ” Review & Audit

Category Key Tools
Pipeline Gates validate_phase_gate, pipeline_heartbeat, validate_project_structure
Review Loop start_review_round, submit_review_round, request_section_rewrite
Pipeline Control pause_pipeline, resume_pipeline, approve_section
Audit & Hooks run_quality_audit, run_writing_hooks, record_hook_event
Self-Evolution run_meta_learning, verify_evolution, apply_pending_evolutions
Domain Constraints check_domain_constraints, evolve_constraint
Data & Health validate_data_artifacts, diagnose_tool_health, check_formatting

๐Ÿ“„ Export & Submission

Category Key Tools
Word Export export_word, list_templates, start_document_session, verify_document
Pandoc Export export_docx, export_pdf, preview_citations, build_bibliography
Submission generate_cover_letter, generate_highlights

๐Ÿงฉ MCP Prompts & Resources

Capability Names / URIs Purpose
Prompts project_bootstrap, draft_section_plan, word_export_checklist Materialize guided prompt workflows through the official MCP prompt API
Resources medpaper://workspace/state, medpaper://workspace/projects, medpaper://templates/catalog Surface live workspace state, project lists, and template metadata via MCP resources

๐Ÿ” pubmed-search MCP Tools (37 tools)

Category Key Tools
Search unified_search, generate_search_queries, parse_pico
Databases PubMed, Europe PMC (fulltext + text mining), CORE (200M+ open access)
Gene/Chem search_gene, get_gene_details, search_compound, search_clinvar
Exploration find_related_articles, find_citing_articles, get_article_references
Export prepare_export (RIS/BibTeX/CSV), get_citation_metrics (iCite RCR)
Session get_session_pmids, list_search_history (survives AI memory limits)

๐Ÿ’ก CGU Creative Tools (13 tools)

Category Key Tools
Ideation generate_ideas, spark_collision, spark_collision_deep
Analysis deep_think, multi_agent_brainstorm
Methods list_methods, select_method, apply_method

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

Feature How to Use Benefit
Wikilinks [[greer2017_27345583]] Link drafts, concept pages, and synthesis notes
Hover Preview Mouse over any [[link]] See abstract without opening file
Backlinks Panel Open reference file See which drafts or wiki notes cite this paper
Graph View Ctrl+Shift+P โ†’ MedPaper: Show Foam Graph: ... Jump directly to Default / Evidence / Writing / Assets / Review
Materialized Views notes/index.md, notes/library/overview.md Review live counts, context hubs, and asset/draft graph nodes
Project Isolation Auto-switches on switch_project Only see current project's references

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, 117 full / 22 compact 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/              # 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
โ”‚
โ”œโ”€โ”€ .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

Status Feature Description
โœ… 3 MCP Servers mdpaper (117 full / 22 compact) + pubmed-search (37) + CGU (13)
โœ… Foam Integration Wikilinks, hover preview, backlinks, named graph views, project isolation
โœ… Project Memory .memory/ for cross-session AI context
โœ… Table 1 Generator Auto-generate baseline characteristics
โœ… Novelty Validation 3-round scoring with 75/100 threshold
โœ… Citation-Aware Editing patch_draft with wikilink validation
โœ… MCP-to-MCP Trust Verified PubMed data via direct HTTP
โœ… Pre-commit Hooks 16 hooks (ruff, mypy, bandit, pytest, prettier...)
๐Ÿ”œ Richer VSX UX TreeView, CodeLens, Diagnostics, and deeper in-editor surfaces (Direction C)
๐Ÿ”œ Pandoc Export Word + LaTeX dual export with CSL citations
๐Ÿ“‹ Systematic Review PRISMA flow, Risk of Bias, meta-analysis
๐Ÿ“‹ AI Writing Intelligence Citation intelligence, coherence engine
๐Ÿ“‹ REST API Mode Expose tools as REST API

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

med_paper_assistant-0.7.7.tar.gz (43.1 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

med_paper_assistant-0.7.7-py3-none-any.whl (542.9 kB view details)

Uploaded Python 3

File details

Details for the file med_paper_assistant-0.7.7.tar.gz.

File metadata

  • Download URL: med_paper_assistant-0.7.7.tar.gz
  • Upload date:
  • Size: 43.1 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for med_paper_assistant-0.7.7.tar.gz
Algorithm Hash digest
SHA256 a2559a1d39b8b3a32ba51e3738e1be842e4794d14de1a7972741ac805434f98c
MD5 91af5499c622dffd471d7abeea8b3fb4
BLAKE2b-256 e495246ff1267b8ad794d4bf8ec65ef70bf770170ff6fcfa988131658e838587

See more details on using hashes here.

Provenance

The following attestation bundles were made for med_paper_assistant-0.7.7.tar.gz:

Publisher: release.yml on u9401066/med-paper-assistant

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file med_paper_assistant-0.7.7-py3-none-any.whl.

File metadata

File hashes

Hashes for med_paper_assistant-0.7.7-py3-none-any.whl
Algorithm Hash digest
SHA256 9b954f2b77843560503af903e4c00bdd6ce2987e09399cd07d6df7308984a17d
MD5 bade3307965ddac7190184035d6019ad
BLAKE2b-256 ee7d842312236c9b7319fc539c18da6028d51ba3c4a3769f1d03c3a41f92eb96

See more details on using hashes here.

Provenance

The following attestation bundles were made for med_paper_assistant-0.7.7-py3-none-any.whl:

Publisher: release.yml on u9401066/med-paper-assistant

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page