# ⛔ ARCHIVED — this code has moved

Migrated into the mcpcentral platform monorepo on 2026-07-23 (ADR-043).

Work here instead: mcpcentral-io/mcpcentral → apps/deep-researcher/

Worker: mcpcentral-deep-researcher

This repository is read-only and kept for history. See DEPRECATED.md.

---

Ollama Deep Researcher DXT Extension

Overview

Ollama Deep Researcher is a Desktop Extension (DXT) that enables advanced topic research using web search and LLM synthesis, powered by a local MCP server. It supports configurable research parameters, status tracking, and resource access, and is designed for seamless integration with the DXT ecosystem.

• Research any topic using web search APIs (Tavily, Perplexity, Exa) and LLMs (Ollama, DeepSeek, etc.)
• Configure max research loops, LLM model, and search API
• Track status of ongoing research
• Access research results as resources via MCP protocol

Features

• Implements the MCP protocol over stdio for local, secure operation
• Defensive programming: error handling, timeouts, and validation
• Logging and debugging via stderr
• Compatible with DXT host environments

Directory Structure

.
├── manifest.json         # DXT manifest (see MANIFEST.md for spec)
├── src/
│   ├── index.ts         # MCP server entrypoint (Node.js, stdio transport)
│   └── assistant/       # Python research logic
│       └── run_research.py
├── README.md            # This documentation
└── ...

Installation & Setup

1. Clone the repository and install dependencies:

git clone 
   cd mcp-server-ollama-deep-researcher
   npm install

2. Install Python dependencies for the assistant:

cd src/assistant
   pip install -r requirements.txt
   # or use pyproject.toml/uv if preferred

3. Set required environment variables for web search APIs:

• For Tavily: TAVILY_API_KEY
• For Perplexity: PERPLEXITY_API_KEY
• For Exa: EXA_API_KEY (Get yours at https://dashboard.exa.ai/api-keys)
• Optional: LANGSMITH_API_KEY, LANGSMITH_TRACING=true, OLLAMA_BASE_URL (defaults to http://localhost:11434)
• Example:

export TAVILY_API_KEY=your_tavily_key
     export PERPLEXITY_API_KEY=your_perplexity_key
     export EXA_API_KEY=your_exa_key

• Prefer not to keep plaintext keys on disk? See Optional: secure secrets with 1Password below.

4. Build the TypeScript server (if needed):

npm run build

5. Run the extension locally for testing:

node dist/index.js
   # Or use the DXT host to load the extension per DXT documentation

Usage

• Research a topic:
• Use the research tool with { "topic": "Your subject" }
• Get research status:
• Use the get_status tool
• Configure research parameters:
• Use the configure tool with any of: maxLoops, llmModel, searchApi

Manifest

See manifest.json for the full DXT manifest, including tool schemas and resource templates. Follows DXT MANIFEST.md.

Logging & Debugging

• All server logs and errors are output to stderr for debugging.
• Research subprocesses are killed after 30 minutes to prevent hangs.
• Invalid requests and configuration errors return clear, structured error messages.

Security & Best Practices

• All tool schemas are validated before execution.
• API keys are required for web search APIs and are never logged.
• MCP protocol is used over stdio for local, secure communication.

Testing & Validation

• Validate the extension by loading it in a DXT-compatible host.
• Ensure all tool calls return valid, structured JSON responses.
• Check that the manifest loads and the extension registers as a DXT.

Troubleshooting

• Missing API key: Ensure TAVILY_API_KEY, PERPLEXITY_API_KEY, or EXA_API_KEY is set in your environment depending on which search API you're using.
• Python errors: Check Python dependencies and logs in stderr.
• Timeouts: Research subprocesses are limited to 30 minutes.

Search API Comparison

• Tavily: Fast, comprehensive web search with raw content extraction
• Perplexity: AI-powered search with natural language summaries and citations
• Exa: Neural search engine optimized for semantic search with highlights

Optional: secure secrets with 1Password

If you use 1Password, you can keep plaintext API keys off your disk and out of your AI coding agent's context. This is opt-in and additive — the plaintext setup above keeps working unchanged. Prerequisites: 1Password for Mac or Linux, the op CLI (brew install --cask 1password-cli), and sqlite3.

Create one 1Password Environment holding these eight variables (the four keys are secret; the rest are non-secret config):

You can import an existing .env directly when creating the Environment. Once it exists, choose any of the three mechanisms below (A is the AI-coding pattern; B is 1Password's recommended MCP launch; C is a fallback for hosts that can't run op).

A. Mounted .env + validation hook (keeps plaintext out of the LLM context)

1Password Environments mount a local .env as a UNIX named pipe (FIFO): contents are streamed on demand to authorized readers and never stored on disk. A Claude Code PreToolUse hook validates the mount before the agent runs shell commands.

1. In the 1Password desktop app, open your Environment → **Destinations → Local .env file → Choose file path → .env → Mount**. Verify with cat .env (approves via Touch ID; auth lasts until 1Password locks).

2. .1password/environments.toml (committed) tells the hook which paths to validate — already set to mount_paths = [".env"].

3. Install the validation hook locally:

git clone https://github.com/1Password/agent-hooks /tmp/agent-hooks
   /tmp/agent-hooks/install.sh --agent claude-code --target-dir .

This creates .claude/claude-code-1password-hooks-bundle/ and .claude/settings.json (both gitignored). The hook is fail-open: if 1Password or sqlite3 is unavailable it allows execution, so non-1Password contributors are unaffected.

4. Test it: echo '{"command":"echo test","workspace_roots":["'"$PWD"'"]}' | .claude/claude-code-1password-hooks-bundle/bin/run-hook.sh 1password-validate-mounted-env-files → {"permission":"allow"} while unlocked, deny with fix instructions when locked.

B. op run --environment for the MCP server launch

Copy .mcp.json.1password.example → .mcp.json (gitignored), replace ` with your Environment ID, and your MCP host will resolve secrets at launch via op run. Non-secret config stays in the env block; secrets are injected from the Environment. The template uses the full path /opt/homebrew/bin/op because GUI-launched hosts (e.g. Claude Desktop) don't inherit your shell $PATH — adjust if your op lives elsewhere (which op`).

**Fallback if your op CLI lacks --environment** (the environment subcommand is part of the 1Password Environments beta and is absent from some builds, e.g. op v2.34.x): use op run --env-file .env against a plain .env of op:// references instead. Create the item once (op item create --vault "Your Vault" --category "Login" --title "ollama-deep-researcher" "TAVILY_API_KEY[concealed]=..." …), then write a gitignored .env of references and point the launcher at it:

```sh

# .env (gitignored) — references only, no plaintext

# TAVILY_API_KEY=op://Your Vault/ollama-deep-researcher/TAVILY_API_KEY

# …

op run --env-file .env -- node build/index.js

```

The same .env also powers Docker (see below), so one references file covers both launch paths. op run prompts Touch ID once per launch.

C. op inject template for .mcp.json

For MCP hosts that can't use op run, copy .mcp.json.template → a working file, replace ` with your vault name, then materialize the {{ op://... }}` references into real values:

op inject -i .mcp.json.template -o .mcp.json

op inject writes the output with filemode 0600. .mcp.json is gitignored. Recompile after rotating secrets in 1Password. (Requires op CLI with standard item/vault support; the op run --environment form in option B additionally requires 1Password Environments beta.)

Docker

docker-compose.yml interpolates all eight vars from the environment. Run compose through op run --env-file so the op:// references in .env (or the FIFO mount, if you set one up in A) are resolved and forwarded into the container:

op run --env-file .env -- docker compose up

References

• DXT Architecture Overview
• DXT Manifest Spec
• DXT Example Extensions
• Model Context Protocol SDK

---