io.github.MohdSaleh/tinyfish-guided-research
This server provides a structured, stateful research workflow on top of TinyFish Search/Fetch, guiding an external LLM client through planning, retrieval, evidence review, claim resolution, citation verification, and finalization.
Start research sessions with configurable mode (FAST, BALANCED, EXHAUSTIVE), contested flag, max rounds, and budget controls.
Validate and store research plans with subagent tasks, queries, retrieval specs, and disconfirming evidence settings.
Run parallel subagent retrieval tracks and compact discovery searches for research gaps.
Search TinyFish with domain type (web/news/research paper), date filters, language, location, domain restrictions, and recency constraints.
Screen sources with verdicts (RELEVANT, PARTIAL, IRRELEVANT) and deduplicate sources across URLs/mirrors.
Register, split, revise, and override atomicity for atomic claims with temporal modes.
Bind direct quotes from sources to claims, ensuring quote presence against fetched content.
Judge evidence with semantic relations (SUPPORTS, CONTRADICTS, RELATED_BUT_INSUFFICIENT, IRRELEVANT) and strength scores.
Assess claim resolution deterministically and get next-step instructions for the client.
Record and track conflicting evidence and cross-claim tensions with optional resolutions.
Research unknown claims via targeted gap plans (support/disconfirm/resolve_conflict).
Verify citations automatically from strongest quote-verified evidence and audit citation coverage.
Finalize research into an auditable synthesis manifest.
Inspect research state for debugging via get_research_state.
Persist state in SQLite or PostgreSQL for multi-step and multi-instance deployments.
Return structured agent rules, quality gates, next actions, and protocol-versioned responses to guide the client workflow.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@io.github.MohdSaleh/tinyfish-guided-research research the impact of remote work on productivity in 2024, citing sources"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TinyFish Guided Research MCP
An MCP server that adds a simple research workflow on top of TinyFish Search and Fetch.
The client model does the reasoning. The server keeps track of the research run, handles the search and fetch flow, stores the state, checks evidence and citations, and tells the client what should happen next.
There is no LLM running inside the server.
How it works
A research run usually follows this flow:
Research request
↓
Plan
↓
Search
↓
Review sources
↓
Fetch useful content
↓
Track claims and evidence
↓
Check what is supported or still missing
↓
Research the gaps
↓
Verify citations
↓
FinalizeSearch results are treated as candidates first, not as evidence by default.
The server also keeps duplicate sources from being counted more than once. This includes cases where the same paper or source appears through different URLs or mirrors.
Quotes are checked against the fetched source content, while semantic decisions such as whether a passage actually supports a claim are left to the client model.
Conflicting evidence is kept in the research state instead of being ignored, and citations are checked before the research is finalized.
Related MCP server: genpark-multihop-research-query-decomposer-skill
What it handles
Research state across multiple steps
TinyFish Search and Fetch calls
Source screening and duplicate handling
Claim and evidence tracking
Quote checks against fetched content
Conflicting evidence
Research gaps and follow-up searches
Citation verification
Research budgets and stopping conditions
SQLite and PostgreSQL persistence
Quick start
Hosted
The hosted MCP endpoint is:
https://tinyfish-guided-research-mcp.fastmcp.app/mcpUse it as a Streamable HTTP MCP server.
Local
Requires Python 3.11+ and a TinyFish API key.
TINYFISH_API_KEY="your-api-key" uvx tinyfish-guided-research-mcpExample MCP client config:
{
"mcpServers": {
"tinyfish-research": {
"command": "uvx",
"args": ["tinyfish-guided-research-mcp"],
"env": {
"TINYFISH_API_KEY": "your-api-key"
}
}
}
}The compatibility entrypoint is also available:
uvx --from tinyfish-guided-research-mcp tinyfish-research-mcpStorage
SQLite is fine for local or single-instance use:
export RESEARCH_DB_PATH="research_state.db"For hosted or multi-instance deployments, use PostgreSQL:
export DATABASE_URL="postgresql://user:password@host:5432/database?sslmode=require"PostgreSQL is the better option when more than one server instance can access the same research state.
Distribution
The server is available through PyPI, the official MCP Registry, and the hosted Horizon endpoint.
PyPI:
tinyfish-guided-research-mcpMCP Registry:
io.github.MohdSaleh/tinyfish-guided-researchHosted MCP:
https://tinyfish-guided-research-mcp.fastmcp.app/mcpDevelopment
Clone the repo and install the dependencies:
git clone https://github.com/MohdSaleh/tinyfish-guided-research-mcp.git
cd tinyfish-guided-research-mcp
uv sync --all-extrasRun it locally:
TINYFISH_API_KEY="your-api-key" uv run tinyfish-guided-research-mcpRun the checks:
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest
uv run python evals/run_evals.py
uv run pip-audit
uv buildThe regular tests cover the implementation and storage layer. The research evals cover cases such as duplicate sources, weak evidence, quote mismatches, superseded claims, and citation coverage.
You can also inspect the MCP tools with:
npx @modelcontextprotocol/inspector \
--cli uv run tinyfish-guided-research-mcp \
--method tools/listDeploying on Horizon
If you want to deploy your own instance with Prefect Horizon, use:
Entrypoint:
src/tinyfish_research_mcp/server.py:mcp
Dependencies:
pyproject.tomlSet:
TINYFISH_API_KEY
DATABASE_URLUse PostgreSQL for hosted deployments instead of the local SQLite fallback.
License
MIT
Available Tools
20 toolsassess_claimsC
Compute deterministic claim resolution and return a complete next-step packet.
Inputs: research_id (required). Returns: data, status, agent_rules, next_action, +2 more
bind_evidenceA
Bind direct source quotations to existing claims and verify quote presence.
This tool does NOT accept semantic stance. Keeping quote binding separate from entailment judgment gives weak client models one bounded operation at a time and prevents a topical passage from becoming support merely because it was attached to a claim.
Inputs: bindings (required), research_id (required). Returns: data, status, agent_rules, next_action, +2 more
check_server_configA
Check API key, DNS, and live TinyFish Search/Fetch endpoint health.
Inputs: no named parameters. Returns: data, status, agent_rules, next_action, +2 more
discovery_searchD
Run a compact additional retrieval wave; later waves consume the global follow-up budget.
Inputs: purpose (required), queries (required), research_id (required), retrieval. Returns: data, status, agent_rules, next_action, +2 more
dispatch_parallel_subagentsB
Execute independent retrieval tracks concurrently and return only a compact review shortlist.
Inputs: research_id (required), tasks. Returns: data, status, agent_rules, next_action, +2 more
finalize_researchC
Finalize into an auditable synthesis manifest; do not generate prose inside the MCP.
Inputs: research_id (required). Returns: data, status, agent_rules, next_action, +2 more
get_research_stateB
Debug/inspection tool. Returns compact protocol state, not full source text.
Inputs: research_id (required). Returns: data, status, agent_rules, next_action, +2 more
get_source_contextA
Return a few relevant passages from persisted full source content.
Use when the client needs a better direct quote without re-fetching the URL.
Inputs: source_id (required), research_id (required), query. Returns: data, status, agent_rules, next_action, +2 more
init_researchB
Start a research session with an explicit latency/coverage profile.
FAST is the default and preserves the same hard evidence gates while fetching/reviewing fewer candidates and stopping resolved claims early.
Inputs: topic (required), mode, contested, max_rounds. Returns: data, status, agent_rules, next_action, +2 more
judge_evidenceB
Assign bounded semantic relation labels to quote-verified evidence.
The server owns evidence IDs and quote integrity. The client does exactly one semantic task here: classify the relationship between the displayed quote and its claim.
Inputs: judgments (required), research_id (required). Returns: data, status, agent_rules, next_action, +2 more
override_atomicityC
Explicitly override an atomicity warning for a maximally atomic claim.
Inputs: reason (required), claim_id (required), research_id (required). Returns: data, status, agent_rules, next_action, +2 more
plan_researchB
Validate and store the research plan before any retrieval.
Inputs: plan (required), research_id (required). Returns: data, status, agent_rules, next_action, +2 more
register_claimsA
Register new claims only; does not accept evidence.
This separation prevents claim creation and evidence judgment from being conflated in one call. Server generates every claim_id.
Inputs: claims (required), research_id (required). Returns: data, status, agent_rules, next_action, +2 more
research_unknownsC
Run targeted retrieval only for claims that still need work, then return one compact review packet.
Inputs: gaps (required), research_id (required). Returns: data, status, agent_rules, next_action, +2 more
review_candidatesA
Unified claim/source review: relevance + direct quote + semantic relation.
Initial broad retrieval still uses screen_sources before claims exist. Once claim IDs exist, this is the preferred path for both initial evidence and targeted gap evidence; bind_evidence/judge_evidence remain low-level compatibility tools rather than the normal happy path.
Inputs: reviews (required), research_id (required). Returns: data, status, agent_rules, next_action, +2 more
review_claim_tensionsA
Record cross-claim tensions after the claim graph is stable.
Mandatory once for contested sessions. Tensions may describe genuine theoretical disagreement even when both claims accurately represent different positions.
Inputs: tensions (required), research_id (required). Returns: data, status, agent_rules, next_action, +2 more
revise_claimA
Replace an incorrect/overbroad active claim without leaving the parent unresolved.
The old claim is superseded automatically. Use this for semantic revision; use split_claim when one claim must become multiple children.
Inputs: claim_id (required), replacement (required), research_id (required). Returns: data, status, agent_rules, next_action, +2 more
screen_sourcesD
Initial semantic source gate over only the server-provided review shortlist.
Inputs: screenings (required), research_id (required). Returns: data, status, agent_rules, next_action, +2 more
split_claimC
Split a compound claim. The parent is superseded automatically.
Inputs: children (required), research_id (required), parent_claim_id (required). Returns: data, status, agent_rules, next_action, +2 more
verify_citationsA
Server-owned citation integrity + coverage audit.
Normal use: pass research_id only. The server automatically selects the strongest quote-verified winning evidence for each strongly resolved claim. Optional citations are accepted only as explicit client overrides.
Inputs: research_id (required), citations. Returns: data, status, agent_rules, next_action, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool has a clearly distinct role in the research pipeline: planning, health checks, initialization, parallel retrieval, discovery, screening, claim lifecycle (register, split, revise, override), evidence binding, judging, assessment, gap targeting, unified review, context retrieval, tension recording, citation audit, finalization, and state inspection. Even overlapping tools like review_candidates vs bind_evidence are explicitly distinguished by the description, leaving no ambiguity for an agent.
All tool names follow a consistent snake_case verb_noun pattern (e.g., plan_research, dispatch_parallel_subagents, verify_citations). The naming convention is uniform and predictable, making it easy for an agent to infer action and target from each name.
With 20 tools, the surface is larger than the typical 3–15 range, but the complexity of the guided research workflow—spanning planning, retrieval, claim management, evidence handling, and finalization—justifies the count. Each tool has a specific purpose and the number is proportionate to the domain's needs, though it is on the heavier side.
The tool set covers the entire research lifecycle: from plan validation and server health checks to parallel retrieval, source screening, claim registration/splitting/revising, evidence binding and judging, claim assessment, targeted gap filling, unified review, tension recording, citation verification, finalization, and state inspection. No obvious dead ends or missing operations are apparent; the surface is comprehensive and well-integrated.
Maintenance
Related MCP Connectors
Machine-native research commons for agent evidence, discovery, rooms, and bounded research quests.
Retrieve citation-ready technical context and coordinate evidence-backed work between AI agents.
Source-traced evidence research for AI agents. We organise the evidence; you decide.
Evidence-backed crypto due diligence with sources, freshness, and a runtime receipt on every call.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables citation-audited deep research with tools for web-grounded answers, source conflict detection, and per-claim citation auditing.MIT
- FlicenseNot gradedqualityBmaintenanceEnables decomposition of complex research queries into multi-hop sub-queries and synthesis DAGs, with scientific consensus analysis, citation credibility verification, and deterministic JSON outputs for MCP-compliant clients.8-
- AlicenseNot gradedqualityBmaintenanceEnables traceable research workflows by searching uploaded sources, verifying citations, routing uncertain or high-risk requests to human review, and streaming answers with an audit trail.MIT
- AlicenseNot gradedqualityBmaintenanceEnables autonomous multi-perspective deep research, evidence harvesting, and verified report synthesis with confidence scoring, directly from MCP-compatible clients.MIT