| Name | turboprop JSON |
| Version |
0.3.4
JSON |
| download |
| home_page | None |
| Summary | Lightning-fast semantic code search and indexing with DuckDB vector operations |
| upload_time | 2025-07-22 02:32:23 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
code
search
semantic
embedding
mcp
ai
indexing
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Turboprop 🚀
**AI-powered semantic code search for developers**
Find code by describing what it does, not just what it's called. Perfect for exploring unfamiliar codebases, debugging, and AI-assisted development with Claude Code.
## Quickstart
### With Claude Code (Recommended)
**Option 1: Default stdio transport (recommended for local development)**
```json
{
"mcpServers": {
"turboprop": {
"command": "uvx",
"args": ["turboprop@latest", "mcp", "--repository", ".", "--auto-index"],
"env": {}
}
}
}
```
**Option 2: HTTP transport (for server deployments)**
```json
{
"mcpServers": {
"turboprop": {
"command": "uvx",
"args": ["turboprop@latest", "mcp", "--transport", "http", "--host", "0.0.0.0", "--port", "8080", "--repository", "."],
"env": {}
}
}
}
```
Then use natural language with Claude:
- "Use turboprop to find JWT authentication code"
- "Search for error handling middleware patterns"
- "Find React components that handle forms"
### Standalone CLI
```bash
# Install and index your codebase
uvx turboprop index .
# Search with natural language
uvx turboprop search "JWT authentication middleware"
uvx turboprop search "database connection setup"
uvx turboprop search "error handling patterns"
```
### Standalone HTTP Server
```bash
# Start HTTP server with all MCP tools exposed as REST API
uvx turboprop@latest server
# Custom host and port
uvx turboprop@latest server --host 0.0.0.0 --port 9000
# Index specific repository
uvx turboprop@latest server --repository /path/to/repo
# Server with custom settings
uvx turboprop@latest server --repository . --max-mb 2.0 --no-auto-index
```
The HTTP server exposes all MCP functionality via REST endpoints at `/mcp/*`.
Visit `http://localhost:8080/docs` for interactive API documentation.
## Features
### 🧠 Semantic Code Search
Find code by describing what it does, not just keywords:
- "JWT token validation" finds auth code across languages
- "form validation logic" discovers input handling
- "database connection setup" locates data layer code
### 🔍 Hybrid Search Modes
- **AUTO** - Automatically picks the best search strategy
- **HYBRID** - Combines semantic understanding with exact text matching
- **SEMANTIC** - Pure conceptual search for similar functionality
- **TEXT** - Fast exact text matching
### 📊 Rich Results
Every search result includes:
- **Confidence scores** (0.0-1.0) showing match quality
- **Language detection** and file types
- **Code context** with syntax highlighting
- **Match explanations** - why each result was selected
- **IDE navigation links** for VS Code, PyCharm, etc.
## Usage
### MCP Tools (with Claude Code)
**Core Search & Indexing:**
- `index_repository` - Build searchable index from your codebase
- `index_repository_structured` - Advanced indexing with detailed JSON response
- `search_code` - Perform semantic search with natural language
- `search_code_structured` - Advanced search with rich JSON metadata
- `search_code_hybrid` - Configurable hybrid semantic + keyword search
**Index Management:**
- `get_index_status` - Check index health and file counts
- `get_index_status_structured` - Comprehensive index status with JSON metadata
- `check_index_freshness_tool` - Validate index currency and freshness
- `watch_repository` - Auto-update index when files change
- `list_indexed_files` - Browse all files in the search index
**Construct-Level Search:**
- `search_functions` - Find functions and methods by purpose
- `search_classes` - Discover classes by functionality (with optional method inclusion)
- `search_imports` - Locate imports and dependencies semantically
- `search_hybrid_constructs` - Multi-granularity construct search with configurable weights
**AI Tool Discovery:**
- `search_mcp_tools` - Find tools using natural language queries with category filtering
- `get_tool_details` - Deep dive into any tool's capabilities with comprehensive metadata
- `list_tool_categories` - Overview of available tool categories and contents
- `search_tools_by_capability` - Search tools by specific technical capabilities
**Tool Analysis & Planning:**
- `recommend_tools_for_task` - Get intelligent tool recommendations with explanations
- `analyze_task_requirements` - Understand task complexity and technical needs
- `suggest_tool_alternatives` - Explore alternative tools for your primary choice
- `recommend_tool_sequence` - Plan optimal multi-step development workflows
**Tool Comparison & Analysis:**
- `compare_mcp_tools` - Compare multiple tools across various dimensions
- `find_tool_alternatives` - Discover similar tools with similarity analysis
- `analyze_tool_relationships` - Analyze relationships between tools and ecosystems
**Tool Browsing:**
- `browse_tools_by_category` - Explore tools within specific functional categories
- `get_category_overview` - High-level view of the entire tool ecosystem
- `get_tool_selection_guidance` - Structured decision support for optimal tool choice
**Quick Commands (Slash Commands):**
- `/search <query>` - Fast semantic search (3 results)
- `/index_current` - Reindex current repository
- `/status` - Show index status
- `/files [limit]` - List indexed files
- `/search_by_type <type> <query>` - Search specific file types
- `/help_commands` - Show available commands
### CLI Commands
```bash
# Index management
turboprop index . # Index current directory
turboprop index ~/project --max-mb 2 # Index with larger file limit
# Search
turboprop search "query" --mode auto # Smart search (recommended)
turboprop search "query" --mode hybrid --explain # Show match reasoning
turboprop search "query" --k 10 # Get 10 results
# Live updates
turboprop watch . # Monitor for file changes
# HTTP Server
turboprop server # Start HTTP server on localhost:8080
turboprop server --host 0.0.0.0 --port 9000 # Custom host and port
turboprop server --repository /path # Serve specific repository
# MCP Server (for Claude Code integration)
turboprop mcp --repository . # Start MCP server for current directory (stdio)
turboprop mcp --transport http --host 0.0.0.0 --port 8080 # HTTP transport
turboprop mcp --transport sse --port 9000 # SSE transport
```
## Search Query Tips
**Be descriptive and specific:**
- ✅ "JWT token validation middleware"
- ❌ "auth"
**Ask conceptual questions:**
- ✅ "how to handle database connection errors"
- ❌ "try catch db"
**Combine multiple concepts:**
- ✅ "React form validation with custom hooks"
- ❌ "react forms"
**Example queries:**
- "JWT token validation and refresh logic"
- "REST API error handling patterns"
- "React component state management"
- "database query optimization"
- "OAuth2 authorization flow implementation"
## HTTP API Usage
The HTTP server exposes all MCP tools as REST API endpoints, making Turboprop accessible from any programming language or system.
### Key Endpoints
**Core Search & Indexing:**
- `POST /mcp/search_code` - Semantic code search
- `POST /mcp/search_code_structured` - Advanced search with JSON metadata
- `POST /mcp/search_code_hybrid` - Hybrid semantic + keyword search
- `POST /mcp/index_repository` - Build searchable code index
- `GET /mcp/index_status` - Check index health
**Construct-Level Search:**
- `POST /mcp/search_functions` - Find functions by purpose
- `POST /mcp/search_classes` - Discover classes by functionality
- `POST /mcp/search_imports` - Search import statements
**Tool Discovery & Management:**
- `POST /mcp/search_mcp_tools` - Find tools using natural language
- `POST /mcp/get_tool_details` - Get detailed tool information
- `POST /mcp/recommend_tools_for_task` - Get intelligent tool recommendations
### Example API Usage
```bash
# Start the server
uvx turboprop@latest server
# Search for authentication code
curl -X POST "http://localhost:8080/mcp/search_code" \
-H "Content-Type: application/json" \
-d '{"query": "JWT authentication middleware", "max_results": 5}'
# Get index status
curl "http://localhost:8080/mcp/index_status"
# Search for specific functions
curl -X POST "http://localhost:8080/mcp/search_functions" \
-H "Content-Type: application/json" \
-d '{"query": "password validation", "max_results": 3}'
```
**Interactive API Documentation:** Visit `http://localhost:8080/docs` for full OpenAPI documentation with request/response schemas and a testing interface.
## MCP Transport Options
Turboprop's MCP server supports multiple transport methods for different use cases:
### stdio (Default)
- **Best for**: Claude Desktop, local development, command-line tools
- **Usage**: `uvx turboprop@latest mcp --repository .`
- **Characteristics**: Process-to-process communication via stdin/stdout
### HTTP Transport
- **Best for**: Web applications, microservices, server deployments
- **Usage**: `uvx turboprop@latest mcp --transport http --host 0.0.0.0 --port 8080`
- **Characteristics**: RESTful HTTP endpoints, easy integration with web services
- **Access**: Direct HTTP requests to MCP endpoints
### SSE (Server-Sent Events)
- **Best for**: Streaming web applications, real-time updates
- **Usage**: `uvx turboprop@latest mcp --transport sse --host 127.0.0.1 --port 9000`
- **Characteristics**: Persistent streaming connection, server push capabilities
Choose the transport that best fits your deployment architecture and integration needs.
## Architecture & Technical Details
**Storage:** DuckDB with 384-dimension vector embeddings
**ML Model:** SentenceTransformer "all-MiniLM-L6-v2"
**Search:** Native vector operations with cosine similarity
**Files:** Indexes all Git-tracked files, respects `.gitignore`
**Index Location:** `.turboprop/code_index.duckdb` in each repository
For detailed technical information, see [ARCHITECTURE.md](ARCHITECTURE.md).
## License
MIT License - use freely in your projects!
---
*Find code by meaning, not just by name.*
Raw data
{
"_id": null,
"home_page": null,
"name": "turboprop",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "code, search, semantic, embedding, mcp, ai, indexing",
"author": null,
"author_email": "Greg Lamp <greg@example.com>",
"download_url": "https://files.pythonhosted.org/packages/a0/cd/b13684e59f3c96f19b9caf315fb0adc7f7b3a1ae5f6578175c3c2f1bae65/turboprop-0.3.4.tar.gz",
"platform": null,
"description": "# Turboprop \ud83d\ude80\n\n**AI-powered semantic code search for developers**\n\nFind code by describing what it does, not just what it's called. Perfect for exploring unfamiliar codebases, debugging, and AI-assisted development with Claude Code.\n\n## Quickstart\n\n### With Claude Code (Recommended)\n\n**Option 1: Default stdio transport (recommended for local development)**\n```json\n{\n \"mcpServers\": {\n \"turboprop\": {\n \"command\": \"uvx\",\n \"args\": [\"turboprop@latest\", \"mcp\", \"--repository\", \".\", \"--auto-index\"],\n \"env\": {}\n }\n }\n}\n```\n\n**Option 2: HTTP transport (for server deployments)**\n```json\n{\n \"mcpServers\": {\n \"turboprop\": {\n \"command\": \"uvx\", \n \"args\": [\"turboprop@latest\", \"mcp\", \"--transport\", \"http\", \"--host\", \"0.0.0.0\", \"--port\", \"8080\", \"--repository\", \".\"],\n \"env\": {}\n }\n }\n}\n```\n\nThen use natural language with Claude:\n- \"Use turboprop to find JWT authentication code\"\n- \"Search for error handling middleware patterns\"\n- \"Find React components that handle forms\"\n\n### Standalone CLI\n```bash\n# Install and index your codebase\nuvx turboprop index .\n\n# Search with natural language\nuvx turboprop search \"JWT authentication middleware\"\nuvx turboprop search \"database connection setup\"\nuvx turboprop search \"error handling patterns\"\n```\n\n### Standalone HTTP Server\n```bash\n# Start HTTP server with all MCP tools exposed as REST API\nuvx turboprop@latest server\n\n# Custom host and port\nuvx turboprop@latest server --host 0.0.0.0 --port 9000\n\n# Index specific repository\nuvx turboprop@latest server --repository /path/to/repo\n\n# Server with custom settings\nuvx turboprop@latest server --repository . --max-mb 2.0 --no-auto-index\n```\n\nThe HTTP server exposes all MCP functionality via REST endpoints at `/mcp/*`. \nVisit `http://localhost:8080/docs` for interactive API documentation.\n\n## Features\n\n### \ud83e\udde0 Semantic Code Search\nFind code by describing what it does, not just keywords:\n- \"JWT token validation\" finds auth code across languages\n- \"form validation logic\" discovers input handling\n- \"database connection setup\" locates data layer code\n\n### \ud83d\udd0d Hybrid Search Modes\n- **AUTO** - Automatically picks the best search strategy\n- **HYBRID** - Combines semantic understanding with exact text matching \n- **SEMANTIC** - Pure conceptual search for similar functionality\n- **TEXT** - Fast exact text matching\n\n### \ud83d\udcca Rich Results\nEvery search result includes:\n- **Confidence scores** (0.0-1.0) showing match quality\n- **Language detection** and file types\n- **Code context** with syntax highlighting\n- **Match explanations** - why each result was selected\n- **IDE navigation links** for VS Code, PyCharm, etc.\n\n## Usage\n\n### MCP Tools (with Claude Code)\n\n**Core Search & Indexing:**\n- `index_repository` - Build searchable index from your codebase\n- `index_repository_structured` - Advanced indexing with detailed JSON response\n- `search_code` - Perform semantic search with natural language\n- `search_code_structured` - Advanced search with rich JSON metadata\n- `search_code_hybrid` - Configurable hybrid semantic + keyword search\n\n**Index Management:**\n- `get_index_status` - Check index health and file counts\n- `get_index_status_structured` - Comprehensive index status with JSON metadata\n- `check_index_freshness_tool` - Validate index currency and freshness\n- `watch_repository` - Auto-update index when files change\n- `list_indexed_files` - Browse all files in the search index\n\n**Construct-Level Search:**\n- `search_functions` - Find functions and methods by purpose\n- `search_classes` - Discover classes by functionality (with optional method inclusion)\n- `search_imports` - Locate imports and dependencies semantically\n- `search_hybrid_constructs` - Multi-granularity construct search with configurable weights\n\n**AI Tool Discovery:**\n- `search_mcp_tools` - Find tools using natural language queries with category filtering\n- `get_tool_details` - Deep dive into any tool's capabilities with comprehensive metadata\n- `list_tool_categories` - Overview of available tool categories and contents\n- `search_tools_by_capability` - Search tools by specific technical capabilities\n\n**Tool Analysis & Planning:**\n- `recommend_tools_for_task` - Get intelligent tool recommendations with explanations\n- `analyze_task_requirements` - Understand task complexity and technical needs\n- `suggest_tool_alternatives` - Explore alternative tools for your primary choice\n- `recommend_tool_sequence` - Plan optimal multi-step development workflows\n\n**Tool Comparison & Analysis:**\n- `compare_mcp_tools` - Compare multiple tools across various dimensions\n- `find_tool_alternatives` - Discover similar tools with similarity analysis\n- `analyze_tool_relationships` - Analyze relationships between tools and ecosystems\n\n**Tool Browsing:**\n- `browse_tools_by_category` - Explore tools within specific functional categories\n- `get_category_overview` - High-level view of the entire tool ecosystem\n- `get_tool_selection_guidance` - Structured decision support for optimal tool choice\n\n**Quick Commands (Slash Commands):**\n- `/search <query>` - Fast semantic search (3 results)\n- `/index_current` - Reindex current repository\n- `/status` - Show index status\n- `/files [limit]` - List indexed files\n- `/search_by_type <type> <query>` - Search specific file types\n- `/help_commands` - Show available commands\n\n### CLI Commands\n```bash\n# Index management\nturboprop index . # Index current directory\nturboprop index ~/project --max-mb 2 # Index with larger file limit\n\n# Search\nturboprop search \"query\" --mode auto # Smart search (recommended)\nturboprop search \"query\" --mode hybrid --explain # Show match reasoning\nturboprop search \"query\" --k 10 # Get 10 results\n\n# Live updates\nturboprop watch . # Monitor for file changes\n\n# HTTP Server\nturboprop server # Start HTTP server on localhost:8080\nturboprop server --host 0.0.0.0 --port 9000 # Custom host and port\nturboprop server --repository /path # Serve specific repository\n\n# MCP Server (for Claude Code integration)\nturboprop mcp --repository . # Start MCP server for current directory (stdio)\nturboprop mcp --transport http --host 0.0.0.0 --port 8080 # HTTP transport\nturboprop mcp --transport sse --port 9000 # SSE transport\n```\n\n## Search Query Tips\n\n**Be descriptive and specific:**\n- \u2705 \"JWT token validation middleware\"\n- \u274c \"auth\"\n\n**Ask conceptual questions:**\n- \u2705 \"how to handle database connection errors\" \n- \u274c \"try catch db\"\n\n**Combine multiple concepts:**\n- \u2705 \"React form validation with custom hooks\"\n- \u274c \"react forms\"\n\n**Example queries:**\n- \"JWT token validation and refresh logic\"\n- \"REST API error handling patterns\"\n- \"React component state management\"\n- \"database query optimization\"\n- \"OAuth2 authorization flow implementation\"\n\n## HTTP API Usage\n\nThe HTTP server exposes all MCP tools as REST API endpoints, making Turboprop accessible from any programming language or system.\n\n### Key Endpoints\n\n**Core Search & Indexing:**\n- `POST /mcp/search_code` - Semantic code search\n- `POST /mcp/search_code_structured` - Advanced search with JSON metadata\n- `POST /mcp/search_code_hybrid` - Hybrid semantic + keyword search\n- `POST /mcp/index_repository` - Build searchable code index\n- `GET /mcp/index_status` - Check index health\n\n**Construct-Level Search:**\n- `POST /mcp/search_functions` - Find functions by purpose\n- `POST /mcp/search_classes` - Discover classes by functionality\n- `POST /mcp/search_imports` - Search import statements\n\n**Tool Discovery & Management:**\n- `POST /mcp/search_mcp_tools` - Find tools using natural language\n- `POST /mcp/get_tool_details` - Get detailed tool information\n- `POST /mcp/recommend_tools_for_task` - Get intelligent tool recommendations\n\n### Example API Usage\n\n```bash\n# Start the server\nuvx turboprop@latest server\n\n# Search for authentication code\ncurl -X POST \"http://localhost:8080/mcp/search_code\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\": \"JWT authentication middleware\", \"max_results\": 5}'\n\n# Get index status\ncurl \"http://localhost:8080/mcp/index_status\"\n\n# Search for specific functions\ncurl -X POST \"http://localhost:8080/mcp/search_functions\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\": \"password validation\", \"max_results\": 3}'\n```\n\n**Interactive API Documentation:** Visit `http://localhost:8080/docs` for full OpenAPI documentation with request/response schemas and a testing interface.\n\n## MCP Transport Options\n\nTurboprop's MCP server supports multiple transport methods for different use cases:\n\n### stdio (Default)\n- **Best for**: Claude Desktop, local development, command-line tools\n- **Usage**: `uvx turboprop@latest mcp --repository .`\n- **Characteristics**: Process-to-process communication via stdin/stdout\n\n### HTTP Transport \n- **Best for**: Web applications, microservices, server deployments\n- **Usage**: `uvx turboprop@latest mcp --transport http --host 0.0.0.0 --port 8080`\n- **Characteristics**: RESTful HTTP endpoints, easy integration with web services\n- **Access**: Direct HTTP requests to MCP endpoints\n\n### SSE (Server-Sent Events)\n- **Best for**: Streaming web applications, real-time updates\n- **Usage**: `uvx turboprop@latest mcp --transport sse --host 127.0.0.1 --port 9000`\n- **Characteristics**: Persistent streaming connection, server push capabilities\n\nChoose the transport that best fits your deployment architecture and integration needs.\n\n## Architecture & Technical Details\n\n**Storage:** DuckDB with 384-dimension vector embeddings \n**ML Model:** SentenceTransformer \"all-MiniLM-L6-v2\" \n**Search:** Native vector operations with cosine similarity \n**Files:** Indexes all Git-tracked files, respects `.gitignore` \n**Index Location:** `.turboprop/code_index.duckdb` in each repository\n\nFor detailed technical information, see [ARCHITECTURE.md](ARCHITECTURE.md).\n\n## License\n\nMIT License - use freely in your projects!\n\n---\n\n*Find code by meaning, not just by name.*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Lightning-fast semantic code search and indexing with DuckDB vector operations",
"version": "0.3.4",
"project_urls": {
"Homepage": "https://github.com/glamp/turboprop",
"Issues": "https://github.com/glamp/turboprop/issues",
"Repository": "https://github.com/glamp/turboprop"
},
"split_keywords": [
"code",
" search",
" semantic",
" embedding",
" mcp",
" ai",
" indexing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ff7da75d0bf55de8004ad21179d59b6051747b7f51a21dd79a1bcad1181f8b33",
"md5": "48838f3fa7b40a673c582c9431d98efa",
"sha256": "3a74bc50a0ca080f7611c71ecc8f04af969111743367d55f94ed6a83c3c4c6ef"
},
"downloads": -1,
"filename": "turboprop-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "48838f3fa7b40a673c582c9431d98efa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 469311,
"upload_time": "2025-07-22T02:32:21",
"upload_time_iso_8601": "2025-07-22T02:32:21.836040Z",
"url": "https://files.pythonhosted.org/packages/ff/7d/a75d0bf55de8004ad21179d59b6051747b7f51a21dd79a1bcad1181f8b33/turboprop-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a0cdb13684e59f3c96f19b9caf315fb0adc7f7b3a1ae5f6578175c3c2f1bae65",
"md5": "2cb396cd9acec239b8a63bd5aa510c0f",
"sha256": "698608cb455dd028f081a34859f2382839d21dcef42429243d789761f07fa4dd"
},
"downloads": -1,
"filename": "turboprop-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "2cb396cd9acec239b8a63bd5aa510c0f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 560684,
"upload_time": "2025-07-22T02:32:23",
"upload_time_iso_8601": "2025-07-22T02:32:23.717102Z",
"url": "https://files.pythonhosted.org/packages/a0/cd/b13684e59f3c96f19b9caf315fb0adc7f7b3a1ae5f6578175c3c2f1bae65/turboprop-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 02:32:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "glamp",
"github_project": "turboprop",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "turboprop"
}
