AGENTS.md

1# PubMed Search MCP Agent Baseline
2 
3Shared workspace guidance for agent clients that can read `AGENTS.md`.
4Use this file for cross-tool baseline rules. Keep agent-specific behavior in
5tool-native locations such as `.github/copilot-instructions.md` or
6`.clinerules/` so the same instruction is not duplicated in multiple places.
7 
8## Scope
9 
10- This repository is a Python MCP server for biomedical literature search.
11- The architecture follows DDD boundaries: presentation -> application -> domain,
12  with infrastructure isolated behind those layers.
13- Search, timeline, pipeline, export, session, and reference verification are
14  product capabilities. MCP tools should remain thin wrappers over those
15  services.
16- Local literature notes default to wiki-note semantics. Foam-compatible
17  wikilinks, MedPaper-style layouts, CSL JSON, and user templates are export
18  profiles under the application export layer, not presentation-only behavior.
19 
20## Cross-tool Rules
21 
22- Use `uv` for dependency management and `uv run` for Python commands in this repo.
23- Fix root causes instead of layering ad-hoc patches.
24- Preserve DDD separation. Do not move business logic into MCP tool files,
25  hooks, or shell scripts.
26- Keep changes minimal and local. Avoid unrelated refactors when solving a
27  focused problem.
28- Update relevant docs when behavior, tool surface, or setup instructions change.
29- When MCP tools are added, removed, or renamed, keep registry, docs, and
30  generated artifacts in sync.
31- When note export behavior changes, keep skills, Copilot instructions, Cline
32  rules, generated docs, and packaged references aligned.
33- The `unicode-mojibake` pre-commit hook scans newly staged diff lines for
34  corrupted emoji/UTF-8 artifacts; restore UTF-8 text instead of accepting
35  garbled glyphs.
36- Prefer existing repo assets over creating parallel variants. If a shared rule
37  belongs here, do not duplicate it in `.clinerules/` or Copilot-only files.
38 
39## Important Paths
40 
41- `.github/copilot-instructions.md`: GitHub Copilot-specific runtime guidance
42- `.clinerules/`: Cline-specific rules and workflows
43- `.vscode/mcp.json`: workspace MCP setup for VS Code / Copilot Chat
44- `.claude/skills/pipeline-persistence/references/`: packaged tutorial copies
45  for agent bundles and VSIX integrations that do not read `docs/site-content/`
46- `scripts/setup-vscode-ai-harness.sh`: install recommended VS Code extensions
47- `docs/INTEGRATIONS.md`: client configuration reference
48 
49## Verification Baseline
50 
51- Narrow changes: run the smallest relevant validation first.
52- Repo-wide validation when integration surfaces change:
53  - `uv run pytest -q`
54  - `uv run mypy src/ tests/`
55  - `uv run python scripts/check_async_tests.py`
56 
57## Shared Constraints
58 
59- Do not add duplicate rule sets across tools. Put shared baseline rules here.
60- Put Cline-only workflow automation in `.clinerules/workflows/`.
61- Put Copilot-only hooks/chatmode/instruction behavior under `.github/`.
62- Keep workspace-level AI assets version-controlled so users get a usable setup
63  immediately after clone or packaging.
64