turingmind-mcp 0.3.0

MCP server for TuringMind cloud - provides type-safe tools for authentication, code reviews, and feedback

TuringMind MCP Server

Model Context Protocol (MCP) server for TuringMind cloud integration. Provides type-safe tools for Claude to authenticate, upload code reviews, fetch repository context, and submit feedback.

Requires Python 3.10+ (MCP SDK requirement)

Why MCP?

Instead of Claude generating raw JSON and curl commands (which can fail silently due to field name mismatches or malformed data), MCP provides:

• Type-safe tool definitions — Claude sees the exact schema
• Validated input — Errors caught before sending
• No endpoint guessing — Correct URLs hardcoded
• Better error messages — Clear feedback on failures
• Simplified login — Device code flow handled by the server

Installation

From PyPI

pip install turingmind-mcp

With pipx (recommended for CLI tools)

pipx install turingmind-mcp

From Source

git clone https://github.com/turingmindai/turingmind-mcp.git
cd turingmind-mcp
pip install -e .

Verify Installation

turingmind-mcp --help

Quick Start

Unified Setup (Recommended)

# Install
pip install turingmind-mcp

# Setup for your platform
turingmind setup claude_desktop  # Claude Desktop
turingmind setup cursor          # Cursor IDE/CLI
turingmind setup claude_cli      # Claude Code CLI

# Diagnose installation
turingmind diagnose

Platform-Specific Setup

TuringMind-MCP supports multiple platforms. Choose your platform:

• Claude Desktop - Native MCP integration
• Claude Code CLI - Command-line with MCP or Skills
• Claude SDK - Programmatic Python access
• Cursor IDE - Native MCP integration
• Cursor CLI - Command-line integration

Manual Setup (Claude Desktop Example)

1. Configure Claude Desktop

Add to your Claude Desktop config file:

Platform	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "turingmind": {
      "command": "turingmind-mcp"
    }
  }
}

2. Restart Claude Desktop

3. Login to TuringMind

In Claude, say: "Log me into TuringMind"

Claude will guide you through the device code flow.

Available Tools

Authentication

Tool	Description
turingmind_initiate_login	Start device code auth flow (no API key needed)
turingmind_poll_login	Complete login and save API key
turingmind_validate_auth	Check API key and account status

Code Review

Tool	Description
turingmind_upload_review	Upload review results to cloud
turingmind_get_context	Get memory context for a repository
turingmind_submit_feedback	Mark issues as fixed, dismissed, or false positive

Tool Reference

turingmind_initiate_login

Start device code authentication flow. No API key required.

Parameters: None

Returns:

• verification_url — URL to open in browser
• user_code — Code to enter when prompted
• device_code — Use with turingmind_poll_login

---

turingmind_poll_login

Poll for authentication completion.

Parameters:

Name	Type	Required	Description
device_code	string	✅	Device code from turingmind_initiate_login

Returns:

• On success: API key (automatically saved to ~/.turingmind/config)
• On pending: Status message to wait and retry
• On expired: Error message to restart flow

---

turingmind_validate_auth

Validate API key and get account info.

Parameters: None

Returns:

• Tier (free, pro, team, enterprise)
• Quota remaining
• User ID

---

turingmind_upload_review

Upload code review results to TuringMind cloud.

Parameters:

Name	Type	Required	Description
repo	string	✅	Repository (owner/repo)
branch	string		Git branch name
commit	string		Git commit SHA
review_type	"quick" | "deep"		Review type (default: quick)
issues	array		List of issues found
raw_content	string		Full review as markdown
summary	object		{critical, high, medium, low} counts
files_reviewed	array		Files that were reviewed

Issue Schema:

{
  "title": "SQL Injection vulnerability",
  "severity": "critical",
  "category": "security",
  "file": "src/db.py",
  "line": 42,
  "description": "User input passed directly to query",
  "cwe": "CWE-89",
  "confidence": 95
}

---

turingmind_get_context

Get memory context for a repository.

Parameters:

Name	Type	Required	Description
repo	string	✅	Repository (owner/repo)

Returns:

• Recent open issues
• Hotspot files (frequent issues)
• Team conventions
• Known false positive patterns

---

turingmind_submit_feedback

Submit feedback on a code review issue.

Parameters:

Name	Type	Required	Description
issue_id	string	✅	Issue ID (e.g., iss_abc123)
action	string	✅	One of: fixed, dismissed, false_positive
repo	string	✅	Repository (owner/repo)
file	string		File path where issue was found
line	integer		Line number of the issue
pattern	string		For false_positive: pattern to skip in future
reason	string		Explanation for the feedback

Actions:

• fixed — Issue was resolved (tracks time-to-fix metrics)
• dismissed — Issue isn't important (lowers future priority)
• false_positive — Not a real issue (adds pattern to memory)

Usage Examples

Login Flow

User: Log me into TuringMind

Claude: I'll start the authentication flow.

[Calls turingmind_initiate_login]

🧠 TuringMind Login Started

Step 1: Open this URL in your browser:
https://app.turingmind.ai/cli-auth?device_code=...

Step 2: Sign in with Google or GitHub

User: Done!

Claude: [Calls turingmind_poll_login with device_code]

✅ Login Successful!
API key has been saved to ~/.turingmind/config

Review with Upload

User: Review my code changes and upload to TuringMind

Claude: [Calls turingmind_validate_auth]
✅ TuringMind Authentication Valid
- Tier: team
- Quota: 495/500 reviews remaining

[Reviews code...]

[Calls turingmind_upload_review]
🧠 Review Uploaded to TuringMind
- Review ID: rev_abc123
- Issues: 3

False Positive Feedback

User: That SQL injection issue was a false positive, we use parameterized queries

Claude: [Calls turingmind_submit_feedback]
🚫 Feedback Submitted
Issue iss_abc123 has been marked as false positive.
Pattern saved: `db.query(sql, params)`
This pattern will be skipped in future reviews.

Configuration

Environment Variables

Variable	Description	Default
TURINGMIND_API_URL	API server URL	https://api.turingmind.ai
TURINGMIND_API_KEY	API key	Read from ~/.turingmind/config
TURINGMIND_DEBUG	Enable debug logging	0

Config File

API credentials are stored in ~/.turingmind/config:

export TURINGMIND_API_KEY=tmk_your_key_here
export TURINGMIND_API_URL=https://api.turingmind.ai

Claude Desktop with Custom API URL

{
  "mcpServers": {
    "turingmind": {
      "command": "turingmind-mcp",
      "env": {
        "TURINGMIND_API_URL": "https://api.turingmind.ai"
      }
    }
  }
}

Development

Setup

git clone https://github.com/turingmindai/turingmind-mcp.git
cd turingmind-mcp
pip install -e ".[dev]"

Run Locally

python -m turingmind_mcp.server

Test with MCP Inspector

npx @modelcontextprotocol/inspector turingmind-mcp

Run Tests

pytest

Lint & Format

ruff check .
black .
mypy src/

Troubleshooting

"TURINGMIND_API_KEY not configured"

Run the login flow in Claude, or set the environment variable:

export TURINGMIND_API_KEY=tmk_your_key_here

"Permission Denied"

API key lacks required permission. Re-run login to create a new key with proper permissions.

"Connection Error"

1. Check that TURINGMIND_API_URL is correct
2. Verify network connectivity
3. For local development, ensure backend is running

Claude doesn't see the tools

1. Verify turingmind-mcp is in your PATH: which turingmind-mcp
2. Check Claude Desktop config is valid JSON
3. Restart Claude Desktop completely (Cmd+Q / close from tray)

License

MIT — see LICENSE for details.

Documentation

Getting Started

• Quick Start Guide - Get started in 5 minutes
• Platform Guides - Platform-specific setup

User Documentation

• Features - Complete feature list and user flows
• Compatibility Matrix - Platform compatibility

Developer Documentation

• Development Guide - Architecture and implementation
• Testing Guide - Testing documentation
• Code Review - Review findings and fixes

See Documentation Index for complete documentation structure.

Links

• TuringMind — AI-powered code review
• Documentation
• GitHub
• Issue Tracker