Skip to content

Scoped Research Agent v0.1.0

Latest
Latest

Choose a tag to compare

View all tags
@scottcollier10 scottcollier10 released this 28 Aug 01:39
v0.1.0
845aa7a

Initial public release.

A one-shot CLI that researches a topic and saves a cited Markdown report.

What it does

  • Isolated sessions per source. Web, GitHub, Notion, and local files each run in
    their own SDK session, configured with only their own MCP server. A web page cannot
    talk the agent into reading your filesystem, because no filesystem tool exists in
    that process to call.
  • Tool-free synthesis. Findings merge in a final session that has no tools and no
    servers at all. Only the application writes to disk, always to
    research/YYYY-MM-DD-topic.md.
  • Everything beyond web search is opt-in via .env, and read-only.
  • Follow-up chat (--chat) against the finished report.

Verification

Runs were verified live and the records are published rather than summarized:

  • docs/live-verification.md — recorded runs, fixtures,
    and measured costs.
  • docs/adversarial-smoke-tests.md — prompt
    injection planted in a web page, a local file, and a GitHub issue body. The GitHub
    payload arrived raw and the agent led its report with the disclosure.
  • docs/decision-log.md — every non-obvious decision and how
    it was checked, including why concurrent subagents were abandoned for sequential
    sessions.

Sample output

examples/ contains a full generated report, published
unedited, next to a manual citation audit. The audit found that 15 of 17 URLs
resolved, all 7 arXiv identifiers matched their claimed papers, and one
precise-sounding statistic was not supported by the source it was attributed to. That
claim was deliberately left in rather than re-rolled away. One run on one topic,
included to show the shape of the output and the character of its errors.

Limits worth knowing before you use it

  • Factual accuracy is not guaranteed. This project constrains tool access and
    provenance. It does not verify facts. A well-sandboxed agent with clean provenance
    can still write a sentence that is wrong.
  • Notion and filesystem read-only is client-enforced. Both servers publish
    mutating tools and offer no read-only switch. This project's tool allowlist is the
    only thing refusing a write.
  • GitHub has an additional server-side layer. The request carries an
    X-MCP-Readonly header the server itself honours, so an unlisted tool is refused
    before the client allowlist is consulted. Note that no server-side refusal was ever
    observed firing during testing, because the allowlist filters the advertised roster
    first.
  • Costs money to run. Recorded runs ranged from about $0.22 to $0.57 depending on
    topic and how many sources were enabled.

Installing

From source only. Not published to PyPI.

git clone https://github.com/scottcollier10/scoped-research-agent.git
cd scoped-research-agent
pip install .

Requires Python 3.10+ and an Anthropic API key. Node.js is needed only for the Notion
and local-file sources.

See README.md for the safety model and
docs/how-to-use.md for usage and gotchas.

Assets 2
Loading