docs-for-dev/SCIENTIFIC_RESEARCH.md
Rama main · réplica de lectura del repositorio original.
# Scientific research workflows
[Handbook](README.md) · [Related guide](TOOLS_AND_CAPABILITIES.md)
DeepTutor mounts `preprint`, `research_audit` and `research_lit` for scientific
paper requests, paper-search-enabled chat, and Deep Research. They are
context-gated tools, separate from the eight user-toggleable tools described
in [Tools and capabilities](TOOLS_AND_CAPABILITIES.md#mounting-rules).
- `preprint(paper, action="read", pages=[...])` reads the primary arXiv PDF,
preserves requested versions and legacy archive IDs, records its SHA-256 and
returns page-level text and original-source links. Downloads are capped at
32 MiB and PDFs at 500 pages; a pass reads at most 20 pages / 36,000 characters.
Coverage and missing extractable text are explicit.
- `preprint(..., action="figures")` selects caption-candidate pages unless the
caller names pages. It renders faithful original pages rather than claiming
automatic figure crops. At most two images go into request-local model
context for a vision-capable model; pixels never enter durable tool metadata.
Links identify the source version and page. Rendering does not prove the
model actually inspected every image.
- `research_audit(paper, repository, ref="HEAD", files=[...], checks=[...])`
resolves a GitHub revision to a commit and reads up to eight static files.
Quote checks require both paper and code quotations to exist in those
fetched sources. Numeric differences are candidates for semantic review:
parameter mapping, units, defaults and active paths still matter. The
Local/admin native reads can use the existing `GITHUB_TOKEN` environment
credential; other accounts use their own authorized MCP connection rather
than borrowing a deployment token. Public API rate-limit/access failures
remain unverified failures. The workflow does not execute downloaded repository code or certify experimental
reproduction. Use full primary text for equations and methods, and report
runtime/environment/data checks that remain unverified.
- `research_lit(topic, followups=[...])` searches primary arXiv metadata, with up
to three explicit follow-up queries, and deduplicates paper identities.
Its matrix records source, author, evidence level and coverage. Read full
papers before assigning agreement/disagreement; Deep Research's APPEND queue
supports recursive investigation of contradictions and evidence gaps.
The report compares claim, method, data, metric, result and limitation with
paper-page and commit-file citations. Author findings, the model's inference,
generated summaries and community annotations remain distinct evidence layers.
Unavailable retrieval is a failure, not an empty set or a verified finding.
## alphaXiv and self-hosted research MCP
The catalog includes the official [alphaXiv MCP endpoint](https://www.alphaxiv.org/docs/mcp)
with OAuth and four research-reading tools: discovery, full-paper text, page
queries and repository files. Library-write tools are not enabled by this
preset. Request `fullText=true` with `get_paper_content` when primary evidence
is needed; its default intermediate report is generated analysis.
Chat and Deep Research use the same account/workspace/partner grant view for
these tools. `preprint(action="mcp", mcp_tool="<qualified name>", arguments={...})`
can invoke an advertised, authorized research-reading operation. A self-hosted
Feynman-style MCP server can expose audit/lit/arxiv/alphaxiv operations or
read-only discussion/annotation operations through this binding.
`preprint(action="discussion")` reads the public alphaXiv paper page and marks
annotation coverage unverified: generated overviews and dynamically omitted
comments must not be presented as the primary paper or a complete discussion
export. The current official MCP documentation does not advertise a dedicated
comments endpoint. If a configured server exposes `get_comments`,
`get_discussions`, `get_annotations` or `get_errata`, that output is explicitly
marked as the community annotation layer; unavailable tools remain unavailable.
## Trusted private MCP origins
An administrator can approve a dedicated remote server origin by setting
`allow_private_network=true` in the admin MCP registry. The editor exposes this
setting; a disabled admin entry may serve as an approval without advertising a
shared tool connection. An account's own server can select the same flag only
when its exact scheme, host and port match a current admin approval.
```json
{
"servers": {
"research_origin_approval": {
"url": "http://research.internal:8080/mcp",
"allow_private_network": true,
"enabled": false
}
}
}
```
The exception permits only RFC1918 Docker/LAN addresses for that origin.
Self-service loopback, cloud-metadata/link-local addresses and other private
origins remain blocked. DNS and approval are checked at connection/request
boundaries and tool admission; revoking the admin flag blocks a pooled
connection's next call. Self-service redirects remain disabled; shared
transport redirects are checked before connecting to their target. This
setting changes neither `web_fetch` nor native paper/repository downloads.
Legacy administrator-owned local/stdio configurations keep their original
behavior. Native arXiv metadata is paced in-process; provider rate-limit errors
remain visible. See the [arXiv API documentation](https://info.arxiv.org/help/api/user-manual.html).
## Implementation and verification
- [deeptutor/tools/research_tools.py](../deeptutor/tools/research_tools.py)
- [deeptutor/services/research/primitives.py](../deeptutor/services/research/primitives.py)
- [tests/services/research/test_primitives.py](../tests/services/research/test_primitives.py)
- [tests/services/research/test_mcp_boundaries.py](../tests/services/research/test_mcp_boundaries.py)