Viveka MCP Server

Viveka is an MCP server for structured, multi-lens reasoning. It gives you 13 critical thinking lenses to think through complex problems, remembers your reasoning across sessions, and surfaces contradictions and assumptions — without ever drawing conclusions for you. The server returns prompts; you do the reasoning.

Quick Start

npx viveka-mcp-server

Zero config. No accounts, no API keys, no cloud dependencies. Runs entirely on your machine. Data persists at ~/.viveka-mcp/.

Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "viveka": {
      "command": "npx",
      "args": ["-y", "viveka-mcp-server"]
    }
  }
}

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "viveka": {
      "command": "npx",
      "args": ["-y", "viveka-mcp-server"]
    }
  }
}

VS Code (Copilot)

Add to your .vscode/mcp.json:

{
  "servers": {
    "viveka": {
      "command": "npx",
      "args": ["-y", "viveka-mcp-server"]
    }
  }
}

Configuration

| Environment Variable | Default | Description | |---|---|---| | VIVEKA_DB_DIR | ~/.viveka-mcp | Directory for persistent data storage |

The 5 Tools

viveka_think — Primary thinking primitive

The core tool. You choose a lens, state your thought, and the server returns a thinking prompt and two next-lens suggestions.

{
  "thought": "I expect this migration to be straightforward",
  "thoughtNumber": 1,
  "totalThoughts": 5,
  "nextThoughtNeeded": true,
  "lens": "enumerate",
  "expectation": "migration is straightforward with no data loss",
  "confidence": "high"
}

Key parameters:

• lens — Which of the 13 lenses to apply (see table below)
• expectation / falsifyingObservation — Pre-commit to what you expect and what would disprove it
• runningConclusion — Your current best answer if forced to stop now
• failureModes — Name 3+ distinct ways this thought could be wrong (required for high confidence)
• revises / supersedes / branchFrom — Cognitive moves: walk back, replace, or fork

Auto lens selection: If you omit the lens parameter, Viveka will automatically detect the best lens from your thought text. The detector uses keyword patterns to map your language to the 13 lenses. If the text is ambiguous, it falls back to "none" (open thinking). You can always override by passing lens explicitly.

When auto-selection occurs, the response includes detectedLens with the inferred lens, confidence score, and autoSelected: true. This transparency lets you see what was chosen and override it in your next call if needed.

With auto lens selection (omit lens):

{
  "thought": "Let me list all the options and categories we might be missing.",
  "thoughtNumber": 1,
  "totalThoughts": 5,
  "nextThoughtNeeded": true
}

Viveka will automatically apply the enumerate lens.

viveka_graph — Recall, audit, and contradiction proposal

14 query types for inspecting the reasoning chain:

| Query Type | What It Returns | |---|---| | transcript | Thoughts in order with lens, provenance, cross-session banners | | stats | Counts by tool, lens, edge type | | propose_contradictions | Candidate claim pairs that share vocabulary | | pre_commit_drift | Expectations that diverged from conclusions | | stability_check | Whether running conclusions have converged | | stagnation_check | Whether recent thoughts are too similar | | weak_claims | High-confidence load-bearing claims with no evidence | | unsupported_claims | Load-bearing claims with no linked evidence | | decision_gate_status | Active decision gates with blocking unknowns | | reasoning_audit | 8 independent audit checks (drift, stagnation, contradictions, weak claims, gates, assumptions, options) | | list_sessions | All sessions for cross-session recall | | vary_assumption | Guidance for perturbing a specific assumption |

viveka_debate — Challenge, defend, evaluate

Structured debate. Challenge a claim, defend it, or evaluate the balance.

{ "mode": "challenge", "claimText": "This system is optimal" }
{ "mode": "defend", "claimText": "Microservices are always better" }
{ "mode": "evaluate", "claimId": "claim_abc123" }

viveka_state — Structured reasoning state

12 operations for tracking objectives, constraints, claims, assumptions, evidence, options, and decision gates:

| Operation | What It Does | |---|---| | set_objective | Set the problem objective | | add_constraint | Add a constraint | | add_claim | Add a claim with type, confidence, status | | update_claim_status | Change claim status (untested/supported/weakened/contradicted/superseded/resolved) | | add_assumption | Add assumption with blast radius and falsification test | | add_evidence | Add evidence with source type and reliability | | link_evidence | Link evidence to a claim | | add_option | Add an option with pros/cons | | add_decision_gate | Add a gate with required evidence and blocking unknowns | | advance_gate | Re-evaluate a gate | | verify_claim | Generate K=3 explanations for stability verification | | query | Query state (highest_risk_assumptions, unsupported_claims, weak_claims, decision_gate_status, all) |

viveka_solve — Curriculum, walkthrough, synthesis

Three modes:

• curriculum — Returns a staged curriculum of lenses with exit criteria and domain-specific prompts
• walkthrough — Detects stuckness and recommends the next lens from the Escalation Ladder
• synthesize — Returns the structured answer shape for your final synthesis

{ "mode": "curriculum", "domain": "migration", "stakes": "high" }
{ "mode": "walkthrough", "sessionId": "session_abc" }
{ "mode": "synthesize", "sessionId": "session_abc" }

The 13 Lenses

| Lens | Reasoning Move | When to Use | |---|---|---| | enumerate | Completeness pressure | When you need to ensure nothing is missed | | discriminate | Signal vs noise, essential vs nonessential | When you need clarity about what truly matters | | field_test | Facts vs assumptions vs projections | When you suspect your own biases are distorting perception | | triangulate | Four perspectives: knowledge, action, purpose, reflection | When you need multiple viewpoints | | falsify | Design cheapest refutation test | When you need to test a conclusion | | outcome_neutral | Action independent of outcome fixation | When you need to act from principle, not outcome bias | | scale_shift | Scale-shifting (hour to generation) | When you need to see the big picture | | audit | Meta-cognitive audit | Before important decisions, or when you suspect bias | | calibrate | Quality classification: clear/driven/fogged | When you need to understand the quality of forces | | progress_test | Real progress vs motion-without-progress | When you're busy but not moving forward | | prioritize | Single-pointed commitment for prioritization under conflict | When competing constraints paralyze action | | decompose | Three-layer decomposition: subjective/material/structural | When you're confused about which scale to think at | | honest_audit | Reasoning hygiene audit: honest vs dishonest moves | When you need to audit the reasoning process itself |

The Escalation Ladder

When viveka_solve in walkthrough mode detects stuckness, it maps the pattern to a specific lens intervention:

| Stuckness Type | Recommended Lens | |---|---| | Repetition without progress | progress_test | | Premature convergence | falsify | | Competing constraints | prioritize | | Confused subject/object | field_test | | Confused scale | decompose | | Confused state of mind | calibrate | | Hygiene drift | honest_audit | | Action/inaction confusion | progress_test |

Cognitive Moves

Viveka supports explicit cognitive moves within viveka_think:

• Branch — Fork an alternative reasoning path with branchFrom / branchId
• Revise — Walk back an earlier thought with revises
• Supersede — Replace an earlier thought entirely with supersedes / supersedeReason
• Pre-commit — State expectation and falsifyingObservation before reading the prompt
• Running conclusion — State your current best answer with runningConclusion (tracked for stability)
• Failure-mode confidence — Name 3+ failureModes to justify high confidence

Domain Templates

11 pre-built curriculum templates with domain-specific prompt overrides:

software_architecture, migration, debugging, incident_response, security_review, product_strategy, research_synthesis, legal_analysis, financial_decision, project_planning, multi_agent_codebase

Edge Types

11 typed edge types in the InsightGraph:

revises, branches_from, applies_lens, challenges, defends, addresses, contradicts, related_to, supersedes, supported_by, challenges_claim

Safety Disclosure

This tool provides structured problem-solving frameworks, not professional advice. When the tool detects medical, legal, financial, or self-harm topics, it appends a safety disclaimer recommending consultation with qualified professionals in your jurisdiction. It never suppresses or refuses to reason — it frames and adds appropriate caveats.

If you or someone you know is in crisis, please contact a crisis helpline in your country or your local emergency services.

Contributing

Contributions are welcome. Reach out to the author to discuss significant changes.

Development

npm install
npm run build
npm test
node dist/index.js

Architecture

• Transport: stdio (MCP standard for local tools)
• State: In-memory InsightGraph with JSON-file persistence at ~/.viveka-mcp/
• Persistence: Atomic writes with 3-level backup rotation and corruption recovery
• Module system: ESM (ES2022, Node16 module resolution)
• Dependencies: @modelcontextprotocol/sdk, zod, nanoid
• Node: >= 18

License

MIT