Smart-Thinking
Smart-Thinking is a Model Context Protocol (MCP) server that delivers graph-based, multi-step reasoning without relying on external AI APIs. Everything happens locally: similarity search, heuristic-based scoring, verification tracking, memory, and visualization all run in a deterministic pipeline designed for transparency and reproducibility.
Core Capabilities
- Graph-first reasoning that connects thoughts with rich relationships (supports, contradicts, refines, contextual links, and more).
- Local TF-IDF + cosine similarity engine powering memory lookups and graph expansion without third-party embedding services.
- Heuristic quality evaluation that scores confidence, relevance, and quality using transparent rules instead of LLM calls.
- Verification workflow with detailed statuses and calculation tracing to surface facts, guardrails, and uncertainties.
- Persistent sessions that can be resumed across runs, keeping both the reasoning graph and verification ledger in sync.
Reasoning Flow
- Session bootstrap –
ReasoningOrchestratorinitializes a session, restores any saved graph state, and prepares feature flags. - Pre-verification – deterministic guards inspect the incoming thought, perform light-weight calculation checks, and annotate the payload.
- Graph integration – the thought is inserted into
ThoughtGraph, linking to context, prior thoughts, and relevant memories. - Heuristic evaluation –
QualityEvaluatorandMetricsCalculatorcompute weighted scores and traces that explain the decision path. - Verification feedback – statuses from
VerificationServiceand heuristic traces are attached to the node and propagated across connections. - Persistence & response – updates are written to
MemoryManager/VerificationMemory, and a structured MCP response is returned with a timeline of reasoning steps.
Each step is logged with structured metadata so you can visualize the reasoning fabric, audit decisions, and replay sessions deterministically.
Installation
Smart-Thinking ships as an npm package compatible with Windows, macOS, and Linux.
Global install (recommended)
npm install -g smart-thinking-mcp
Run with npx
npx -y smart-thinking-mcp
Install via Smithery
npx -y @smithery/cli install @Leghis/smart-thinking --client claude
From source
git clone https://github.com/Leghis/Smart-Thinking.git
cd Smart-Thinking
npm install
npm run build
npm link
Need platform-specific configuration details? See
GUIDE_INSTALLATION.mdfor step-by-step instructions covering Windows, macOS, Linux, and Claude Desktop integration.
Quick Tour
smart-thinking-mcp— start the MCP server (globally installed package).npx -y smart-thinking-mcp— launch without a global install.npm run start— execute the built server from source.npm run demo:session— run the built-in CLI walkthrough that feeds sample thoughts through the reasoning pipeline and prints the resulting timeline.
The demo script showcases how the orchestrator adds nodes, evaluates heuristics, and records verification feedback step by step.
MCP Client Compatibility
Smart-Thinking is validated across the most popular MCP clients and operating systems. Use the new connector mode (--mode=connector or SMART_THINKING_MODE=connector) when a client only accepts the search and fetch tools required by ChatGPT connectors.1
| Client | Transport | Notes |
|---|---|---|
| ChatGPT Connectors & Deep Research | HTTP + SSE | Deploy with SMART_THINKING_MODE=connector node build/index.js --transport=http --host 0.0.0.0 --port 8000. Point ChatGPT to https://<host>/sse and keep only search/fetch enabled, aligning with OpenAI’s remote MCP guidance.1 |
| OpenAI Codex CLI & Agents SDK | Streamable HTTP / SSE | Configure the Codex agent with http://localhost:3000/mcp or http://localhost:3000/sse and set SMART_THINKING_MODE=connector when only knowledge retrieval is needed.2 |
| Claude Desktop / Claude Code | stdio | Add "command": "smart-thinking-mcp" (or an npx command) to claude_desktop_config.json. Full toolset is available.3 |
| Cursor IDE | stdio / SSE / Streamable HTTP | Add the server to ~/.cursor/mcp.json or the project .cursor/mcp.json. Cursor supports prompts, roots, elicitation, and streaming.4 |
| Cline (VS Code) | stdio | Place the command in ~/Documents/Cline/MCP/smart-thinking.json or use the in-app marketplace to register the toolset.3 |
| Kilo Code | stdio | Register via the MCP marketplace and run the server locally; Smart-Thinking exposes deterministic tooling for autonomous edits.3 |
Need a minimal deployment footprint? Combine
--transport=http --mode=connectorwith a reverse proxy (ngrok, fly.io, render, etc.) so remote clients can consume the server without exposing the full toolset.
Configuration & Feature Flags
feature-flags.tstoggles advanced behaviours such as external integrations (disabled by default) and verbose tracing.config.tsaligns platform-specific paths and verification thresholds.memory-manager.tsandverification-memory.tsstore session graphs, metrics, and calculation results using deterministic JSON snapshots.
Development Workflow
npm run build # Compile TypeScript sources
npm run lint # ESLint across src/
npm run test # Jest test suite
npm run test:coverage # Jest coverage report
npm run watch # Incremental TypeScript compilation
See TRANSFORMATION_PLAN.md for the full transformation history and the checklist that drives ongoing hardening.
Quality & Support
- Deterministic heuristics and verification eliminate dependency on remote LLMs.
- Coverage targets: ≥80 % on persistence modules, ≥60 % branch coverage across orchestrator logic.
- CI recommendations: run
npm run lintandnpm run test:coveragebefore each release candidate.
Contributing
Contributions are welcome. Please open an issue or pull request describing the change, and run the quality checks above before submitting.
License
Footnotes
-
OpenAI, “Building MCP servers for ChatGPT and API integrations,” highlights that connectors require
searchandfetchtools for remote use. (https://platform.openai.com/docs/mcp) ↩ ↩2 -
OpenAI Agents SDK documentation on MCP transports (stdio, SSE, streamable HTTP). (https://openai.github.io/openai-agents-python/mcp/) ↩
-
Model Context Protocol client catalogue listing Claude, Cline, Kilo Code, and other MCP-compatible applications. (https://modelcontextprotocol.io/clients) ↩ ↩2 ↩3
-
Cursor documentation for configuring MCP servers via stdio/SSE/HTTP transports. (https://cursor.com/docs/context/mcp) ↩