You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 7fb97e8
Browse filesBrowse the repository at this point in the historyBrowse files
A thinking-augmented MCP (Model Context Protocol) server that gives Claude deep research and reasoning tools. When connected, Claude can search the web, read URLs, find academic papers, search GitHub, plan multi-step tasks, record thoughts, manage in-session memory, and write reports — all while exposing its reasoning trace.
3
+
# 🧠 ThinkMCP
4
4
5
-
## What It Is
5
+
**A local-first research agent that shows its work — built end-to-end on the Model Context Protocol.**
6
6
7
-
ThinkMCP wraps 13 tools across four categories into a single MCP server:
7
+
Qwen 3 thinks, plans, searches, self-critiques, and writes reports — entirely on your machine.
8
+
No cloud LLM. No API bill. Every thought and tool call streamed live to the screen.
8
9
9
-
| Category | Tools |
10
-
|-----------|-------|
11
-
| Research |`web_search`, `fetch_url`, `search_papers`, `search_code`|
Ask a research question. The agent **plans** an approach, **searches** the web, ArXiv, and GitHub, **remembers** what it finds, **critiques** its own draft, and delivers a sourced answer — while the UI renders every reasoning step and tool invocation the moment it happens. Export any session as Markdown or JSON.
37
32
38
-
```bash
39
-
export ANTHROPIC_API_KEY="sk-ant-..."
40
-
export TAVILY_API_KEY="tvly-..."
41
-
export GITHUB_TOKEN="ghp_..."# optional
42
-
```
33
+
The same 13-tool MCP server also plugs straight into **Claude Desktop, Cursor, or VS Code**.
43
34
44
-
## Run the Streamlit UI
35
+
## Engineering highlights
45
36
46
-
```bash
47
-
streamlit run app.py
37
+
These are deliberate design decisions, not defaults:
38
+
39
+
- 🔌 **The agent is a real MCP client — not a wrapper.** It spawns the server as a subprocess, discovers tools over the protocol (`tools/list`), and invokes them with `tools/call` ([agent/mcp_client.py](agent/mcp_client.py)). Zero hardcoded tool schemas; add a tool to the server and the agent picks it up automatically. This is the exact integration path Claude Desktop uses.
40
+
- 🏠 **Local-first inference.** The reasoning loop runs on Qwen 3 via Ollama ([agent/thinking_agent.py](agent/thinking_agent.py)), capturing the model's native thinking stream — with automatic fallback to parsing inline `<think>` tags for instruct-only variants. Works fully offline except optional web search.
41
+
- 📡 **True live streaming.** The agent emits events (`thinking`, `tool_call`, `tool_result`) through a callback; the Streamlit UI drains them from a thread-safe queue and renders mid-run — no waiting for completion ([app.py](app.py)).
42
+
- 💾 **Durable memory.**`remember`/`recall` are SQLite-backed ([server/tools/memory.py](server/tools/memory.py)), so findings survive restarts and are shared between the UI agent and any connected MCP host.
43
+
- 🚦 **Two transports, one server.** stdio for desktop hosts, Streamable HTTP for remote/multi-client deployments — selected at launch, not forked code.
44
+
- ✅ **Tested and linted in CI.** 31 pytest cases covering tools, agent helpers, and server registration, plus ruff — on Python 3.10 and 3.12 for every push.
45
+
46
+
## The 13 tools
47
+
48
+
| Category | Tools | Notes |
49
+
|-----------|-------|-------|
50
+
| Research |`web_search` · `fetch_url` · `search_papers` · `search_code`| Tavily, raw HTTP, ArXiv, GitHub |
Opens at `http://localhost:8501` — pick your model in the sidebar (installed models are auto-detected) and run a query.
115
+
116
+
> Defaults are env-overridable: `THINKMCP_MODEL=qwen3:14b`, `OLLAMA_HOST=http://...`
102
117
103
-
## Add to VS Code (Copilot / MCP extension)
118
+
## Use the server from Claude Desktop / Cursor / VS Code
104
119
105
-
With the [MCP extension](https://marketplace.visualstudio.com/items?itemName=anthropics.claude-vscode) or a compatible client, add to your `.vscode/mcp.json`:
120
+
**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
├── mcp_config.json # template config for MCP clients
202
+
├── tests/ # pytest suite
203
+
├── app.py # Streamlit UI with live-streaming trace
204
+
├── pyproject.toml
184
205
└── Dockerfile
185
206
```
186
207
187
-
## Reports
208
+
## Design notes
209
+
210
+
-`critique` and `plan` are **deterministic heuristics by choice** — instant, free, and reproducible. The LLM does the reasoning; these tools provide structure and a self-check ritual without burning tokens or adding nondeterminism.
211
+
- Thinking capture degrades gracefully: native thinking stream when the model supports it, inline `<think>`-tag parsing when it doesn't.
212
+
213
+
## Roadmap
188
214
189
-
`write_report` saves markdown files to `THINKMCP_REPORTS_DIR` (default: `./reports/`). Files are timestamped: `report_my_topic_20240507_143022.md`.
215
+
-[ ] Benchmark: answer quality with vs. without the reasoning tools on a fixed question set
216
+
-[ ] LLM-judged critique mode (local, via Ollama) as an opt-in alternative to heuristics
217
+
-[ ] Semantic memory recall (embeddings over the SQLite store)
0 commit comments