Skip to main content
Glama

flori

Web research tools exposed over MCP: search, read, open, grep, corpus_search, corpus_list, cite. See spec.md for the design, DECISIONS.md for the open questions resolved during the build, and HANDOFF.md for what still needs a Kagi key.

Layout

  • src/flori/ tool server (types, ports, tools module, SQLite store, adapters, MCP wrapper)

  • fetcher/ isolated fetch process (OCI image; Crawl4AI, headless Chromium, PyMuPDF)

  • tests/ tool-server tests; tests/fetcher/ and tests/e2e/ need the container up

  • fetcher/tests/ fetcher unit tests, runnable on the host

Related MCP server: myscrape

Run

# 1. build and start the fetcher (Docker/OrbStack; Apple container works the same way)
cd fetcher && DOCKER_BUILDKIT=0 /usr/local/bin/docker build -f Containerfile -t flori-fetcher:dev . && cd ..
./scripts/fetcher-up.sh            # also starts the test fixture server

# 2. test
uv run pytest                      # container tests skip if the fetcher is down
(cd fetcher && uv run pytest)
KAGI_API_KEY=... uv run pytest -m live

# 3. serve over MCP (stdio)
KAGI_API_KEY=... FETCHER_URL=http://127.0.0.1:8765 uv run flori
FLORI_TRANSPORT=http FLORI_PORT=8000 uv run flori     # streamable HTTP instead

MCP client config (stdio):

{
  "mcpServers": {
    "flori": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/flori", "flori"],
      "env": {"KAGI_API_KEY": "...", "FETCHER_URL": "http://127.0.0.1:8765"}
    }
  }
}

Configuration: [tool.flori] in pyproject.toml for non-secrets (search_engine, db_path, fetcher_url, search_limit); env vars KAGI_API_KEY, FETCHER_URL, FLORI_DB_PATH, FLORI_SESSION_ID, FLORI_TRANSPORT.

Acceptance

./scripts/fetcher-up.sh
KAGI_API_KEY=... uv run python tests/e2e/acceptance.py

Available Tools

7 tools
citeA

Convert an inspected span of a stored page into a citation. Validates that the page is stored and 0 <= start < end <= len(text) within the length cap, records the verbatim span as an EvidenceEntry, and returns it.

Inputs: url (required), span (required). Returns: object

corpus_listC

Retrieve across the accumulated corpus by metadata: URL, domain, length, fetch time, how many searches surfaced the page, how many evidence entries cite it, and its CSL-JSON record.

Inputs: filter. Returns: object

grepA

Query a stored source, or the whole corpus when url is omitted, with a regular expression. Returns matches with character offsets; results are capped.

Inputs: pattern (required), url. Returns: object

openB

Inspect a stored source in full: returns a window of the stored page text starting at offset with up to length characters (capped).

Inputs: url (required), length (required), offset (required). Returns: object

readA

Read a discovered source against a goal and capture citable evidence. Fetches and stores the page on first access (no fetch if already stored), selects the heading sections around the passages most relevant to goal, records each as an EvidenceEntry (with the scoring chunk offsets in hits), and returns them. max_chars bounds the total text returned (500 to 20000). Refuses any URL not returned by a prior search in this session.

Inputs: url (required), goal (required), max_chars. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 7 tools

    Disambiguation4/5

    Each tool has a fairly distinct role: search discovers URLs, read extracts goal-relevant evidence, open inspects raw windows, grep is regex retrieval, corpus_search/corpus_list retrieve across the accumulated corpus, and cite builds citations. The main soft spot is that read, open, and grep all surface text from stored pages, so an agent must read carefully to pick the right one, but the descriptions differentiate them well.

    Naming Consistency3/5

    Most names are bare verbs (search, read, open, grep, cite) while the corpus family uses a prefix (corpus_search, corpus_list), so conventions are mixed. It is still readable and the corpus_ prefix sensibly groups related tools, but there is no single predictable pattern.

    Tool Count5/5

    Seven tools is well-scoped for a search-read-cite research workflow, with each tool earning a clear place in the pipeline (discovery, reading, inspection, corpus retrieval, citation). No redundancy or padding.

    Completeness4/5

    The core research lifecycle is covered: discover sources, read them against a goal, inspect/grep stored text, search the corpus, and create citations. Minor gaps exist, such as no explicit bibliography export, no tool to list/prioritize collected evidence, and no way to unregister a source, but agents can work around these.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Provides local-first web intelligence over MCP with tools for search, fetch, crawl, extract, cache, find-similar, research, and autonomous agent loops, requiring no API keys.
      10
      1,085 npm
      5,544
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      A self-contained web-research MCP server that lets local LLM agents search, fetch, and synthesize web content using tools like web_search, web_fetch, and web_research.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to perform web research in one tool call by searching, fetching and cleaning full pages, and ranking cited passages. Provides web_research, web_fetch, web_search, and status tools for MCP clients.
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to perform unified web research through a single MCP server, including search, page fetching, recursive crawling, document parsing, YouTube transcript extraction, and deep multi-query research.
      3
      -