qc-lean-mcp 1.2.0__tar.gz

qc_lean_mcp-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TheFractalyst
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qc_lean_mcp-1.2.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: qc-lean-mcp
+Version: 1.2.0
+Summary: QuantConnect/Lean MCP server - 6 tools for docs lookup, code validation, and code generation
+Author: TheFractalyst
+License: MIT License
+        
+        Copyright (c) 2025 TheFractalyst
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/TheFractalyst/QuantConnectMCP
+Project-URL: Repository, https://github.com/TheFractalyst/QuantConnectMCP
+Project-URL: Issues, https://github.com/TheFractalyst/QuantConnectMCP/issues
+Keywords: mcp,quantconnect,lean,algorithmic-trading,quant,trading
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: fastmcp<4.0.0,>=3.0.0
+Requires-Dist: chromadb<1.0.0,>=0.5.0
+Requires-Dist: sentence-transformers<4.0.0,>=3.0.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: python-dotenv<2.0.0,>=1.0.0
+Requires-Dist: loguru<1.0.0,>=0.7.0
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: rapidfuzz<4.0.0,>=3.0.0
+Requires-Dist: xxhash<4.0.0,>=3.0.0
+Requires-Dist: starlette<1.0.0,>=0.36.0
+Provides-Extra: pipeline
+Requires-Dist: playwright>=1.40.0; extra == "pipeline"
+Requires-Dist: beautifulsoup4>=4.12.0; extra == "pipeline"
+Requires-Dist: lxml>=5.0.0; extra == "pipeline"
+Requires-Dist: tqdm>=4.66.0; extra == "pipeline"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file

qc_lean_mcp-1.2.0/README.md

@@ -0,0 +1,201 @@
+[![QuantConnectMCP](/TheFractalyst/QuantConnectMCP/raw/main/assets/banner.svg)](https://github.com/TheFractalyst/QuantConnectMCP)
+
+[![PyPI](https://img.shields.io/pypi/v/quantconnect-mcp?color=blue)](https://pypi.org/project/quantconnect-mcp/)
+[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)](https://python.org/)
+[![ChromaDB](https://img.shields.io/badge/ChromaDB-FF6F00)](https://trychroma.com/)
+[![MCP](https://img.shields.io/badge/MCP-Protocol-blue)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://github.com/TheFractalyst/QuantConnectMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/TheFractalyst/QuantConnectMCP/actions/workflows/ci.yml)
+
+Complete QuantConnect/Lean reference documentation MCP server with 1265 entries
+covering 100% of the official QuantConnect v2 documentation sitemap.
+
+[Quick Start](#quick-start) |
+[Tools](#tools) |
+[Configuration](#configuration) |
+[Database](#database) |
+[Development](#development)
+
+---
+
+## One Command. Two Minutes. Fully Functional.
+
+```bash
+pip install quantconnect-mcp
+quantconnect-mcp
+```
+
+That's it. On first run, the server auto-builds the ChromaDB vector store from
+shipped JSON data (takes 30-60 seconds for embedding model download + indexing).
+Subsequent runs start instantly.
+
+**What you get:**
+
+- 6 MCP tools for QuantConnect/Lean docs lookup, code validation, and template generation
+- 1265 entries indexed in a local ChromaDB vector store (100% offline)
+- Sub-millisecond hot cache for priority lookups
+- Python AST validation for Lean algorithms
+- Common Python.NET issue detection and auto-repair
+- Works with Claude Desktop, Cursor, Windsurf, OpenCode, and any MCP client
+
+**What you need:**
+
+- Python 3.10+
+- Any MCP-compatible AI client
+
+---
+
+## Why QuantConnectMCP?
+
+AI coding assistants hallucinate Lean API syntax. The QuantConnect API is large
+(QCAlgorithm, Algorithm Framework, 200+ indicators, multiple asset classes) and
+constantly evolving. Models trained on older code get method signatures wrong.
+
+QuantConnectMCP gives AI assistants **authoritative, real-time access** to the
+complete QuantConnect/Lean reference:
+
+- **100% coverage**: 1257/1257 official QuantConnect v2 docs sitemap URLs
+- **Semantic search**: Vector embeddings find relevant docs by meaning, not keywords
+- **Code validation**: `qc_validate` checks Python Lean algorithms for common mistakes
+- **Auto-repair**: `qc_repair` fixes Python.NET bridge issues, missing self. prefix, etc.
+- **Code generation**: `qc_scaffold` generates validated algorithm templates
+- **100% local**: No network calls at runtime (ChromaDB auto-builds from shipped data)
+
+---
+
+## Tools
+
+```
++---------------------------+----------------------------------------------+
+| Tool                      | Description                                  |
++---------------------------+----------------------------------------------+
+| qc_lookup(name, kind?)    | Get complete docs for a symbol by exact name |
+| qc_search(query, ...)     | Semantic search across all docs              |
+| qc_browse(namespace, ...) | Enumerate all members of a namespace         |
+| qc_validate(code?, ...)   | Validate Python syntax for Lean algorithms   |
+| qc_repair(code, context)  | Fix common Python.NET issues in Lean code    |
+| qc_scaffold(kind, name)   | Generate algorithm/indicator/research template|
++---------------------------+----------------------------------------------+
+```
+
+---
+
+## Quick Start
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "quantconnect-mcp": {
+      "command": "quantconnect-mcp"
+    }
+  }
+}
+```
+
+### Cursor / Windsurf / OpenCode
+
+```json
+{
+  "mcpServers": {
+    "quantconnect-mcp": {
+      "command": "quantconnect-mcp"
+    }
+  }
+}
+```
+
+### SSE (HTTP)
+
+```bash
+quantconnect-mcp
+# Then connect to http://localhost:8080
+```
+
+Or with environment variables:
+
+```bash
+TRANSPORT=sse PORT=8080 quantconnect-mcp
+```
+
+---
+
+## Configuration
+
+```
++-------------------------+---------------+--------------------------------+
+| Env Var                 | Default       | Description                    |
++-------------------------+---------------+--------------------------------+
+| TRANSPORT               | stdio         | Transport: stdio or sse        |
+| PORT                    | 8080          | Port for SSE transport         |
+| QC_DB_PATH              | ./qc_db       | ChromaDB path                  |
+| QC_COLLECTION           | qc_reference  | ChromaDB collection name       |
+| QC_EMBED_MODEL          | all-MiniLM-L6 | Sentence transformer model     |
+| QC_MAX_RESULTS          | 100           | Max search results             |
+| LOG_LEVEL               | INFO          | Logging level                  |
+| LAZY_MODEL              | 0             | Skip model preload at startup  |
++-------------------------+---------------+--------------------------------+
+```
+
+---
+
+## Database
+
+- 1265 entries (QuantConnect v2 docs)
+- 1257/1257 sitemap URLs (100% coverage)
+- 20 namespaces: cloud, indicators, writing-algorithms, cli, docs, datasets,
+  research, securities, reality-modeling, local, engine, ai, framework, etc.
+- Hot cache for sub-millisecond priority lookups
+- Auto-built on first run from shipped JSON data (14MB)
+
+To rebuild the database:
+
+```bash
+quantconnect-mcp build
+```
+
+---
+
+## Development
+
+```
+git clone https://github.com/TheFractalyst/QuantConnectMCP.git
+cd QuantConnectMCP
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+### Re-index ChromaDB
+
+```bash
+python pipeline/merge_and_index.py --reset
+```
+
+## Docker
+
+```bash
+docker build -t quantconnect-mcp .
+docker run -p 8080:8080 -e TRANSPORT=sse quantconnect-mcp
+```
+
+## Tech Stack
+
+- **FastMCP 3.0** - MCP server framework with FileSystemProvider auto-discovery
+- **ChromaDB** - Local vector database for semantic search (cosine, 384-dim)
+- **SentenceTransformers** - `all-MiniLM-L6-v2` embedding model
+- **RapidFuzz** - Fuzzy string matching for name lookups
+- **Loguru** - Structured logging
+
+## Links
+
+- [fractalyst.dev](https://fractalyst.dev/) - Portfolio
+- [QuantConnect Documentation](https://www.quantconnect.com/docs/v2/) - Official docs
+- [LEAN Engine](https://www.quantconnect.com/lean) - Open-source algorithmic engine
+- [@TheFractalyst](https://x.com/TheFractalyst) - X / Twitter
+
+## License
+
+MIT - see [LICENSE](LICENSE)

qc_lean_mcp-1.2.0/assets/banner.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="800" height="120" viewBox="0 0 800 120">
+  <rect width="800" height="120" fill="#0d1117"/>
+  <rect x="0" y="0" width="6" height="120" fill="#58a6ff"/>
+  <text x="40" y="55" font-family="monospace" font-size="36" font-weight="bold" fill="#58a6ff">QuantConnectMCP</text>
+  <text x="40" y="85" font-family="monospace" font-size="16" fill="#8b949e">QuantConnect/Lean Reference - MCP Server</text>
+  <text x="40" y="105" font-family="monospace" font-size="13" fill="#6e7681">1265 entries | 100% sitemap coverage | 6 tools</text>
+</svg>

qc_lean_mcp-1.2.0/core/build_db.py

@@ -0,0 +1,197 @@
+"""
+core/build_db.py
+Auto-build ChromaDB from shipped JSON data on first run.
+
+Ships data/qc_entries.json (14MB, 1265 entries) as package data.
+On first server start, if no ChromaDB exists at DB_PATH, builds it automatically.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from core.config import COLLECTION, DB_PATH, EMBED_MODEL
+
+
+def _data_json_path() -> Path:
+    return Path(__file__).resolve().parent.parent / "data" / "qc_entries.json"
+
+
+def _build_document_text(entry: dict[str, Any]) -> str:
+    parts: list[str] = []
+
+    name = entry.get("name", "")
+    namespace = entry.get("namespace") or ""
+    category = entry.get("category", "")
+    parts.append(f"{category.upper()}: {name}")
+    if namespace:
+        parts.append(f"Namespace: {namespace}")
+
+    syntax = entry.get("syntax") or ""
+    if not isinstance(syntax, str):
+        syntax = str(syntax)
+    if syntax:
+        parts.append(f"Syntax: {syntax}")
+
+    description = entry.get("description") or ""
+    if not isinstance(description, str):
+        description = str(description)
+    if description:
+        parts.append(description)
+
+    returns = entry.get("returns") or ""
+    if not isinstance(returns, str):
+        returns = str(returns)
+    if returns:
+        parts.append(f"Returns: {returns}")
+
+    remarks = entry.get("remarks") or ""
+    if not isinstance(remarks, str):
+        remarks = str(remarks)
+    if remarks:
+        parts.append(f"Remarks: {remarks}")
+
+    parameters = entry.get("parameters") or []
+    if parameters:
+        parts.append("PARAMETERS:")
+        for p in parameters:
+            if isinstance(p, dict):
+                pname = p.get("name", "?")
+                ptype = p.get("type", "")
+                pdesc = p.get("description", "")
+                parts.append(f"  {pname} ({ptype}): {pdesc}")
+
+    examples = entry.get("examples") or []
+    if examples:
+        parts.append("EXAMPLES:")
+        for ex in examples:
+            parts.append(str(ex))
+
+    return "\n\n".join(parts)
+
+
+def _flatten_metadata(entry: dict[str, Any]) -> dict[str, Any]:
+    meta: dict[str, Any] = {}
+    meta["name"] = entry.get("name", "")
+    meta["category"] = entry.get("category", "")
+    meta["namespace"] = entry.get("namespace") or ""
+    meta["syntax"] = entry.get("syntax") or ""
+    meta["version"] = entry.get("version") or ""
+    meta["returns"] = entry.get("returns") or ""
+    meta["remarks"] = entry.get("remarks") or ""
+    meta["url"] = entry.get("url") or ""
+    meta["scraped_at"] = entry.get("scraped_at") or ""
+    meta["raw_description"] = entry.get("description") or ""
+
+    examples = entry.get("examples") or []
+    parameters = entry.get("parameters") or []
+    meta["has_examples"] = 1 if examples else 0
+    meta["example_count"] = len(examples)
+    meta["param_count"] = len(parameters)
+
+    if isinstance(examples, list):
+        meta["raw_examples"] = " ||| ".join(str(ex) for ex in examples)
+    elif examples:
+        meta["raw_examples"] = str(examples)
+    else:
+        meta["raw_examples"] = ""
+
+    meta["raw_parameters"] = json.dumps(parameters, ensure_ascii=False) if parameters else ""
+
+    sources = entry.get("sources", [])
+    meta["sources"] = ", ".join(sources) if isinstance(sources, list) else str(sources)
+
+    return meta
+
+
+def build_db(force: bool = False) -> int:
+    """Build ChromaDB from shipped JSON data.
+
+    Args:
+        force: If True, delete existing collection and rebuild.
+
+    Returns:
+        Number of entries indexed.
+    """
+    json_path = _data_json_path()
+    if not json_path.exists():
+        logger.error(f"Data file not found: {json_path}")
+        return 0
+
+    logger.info(f"Building ChromaDB from {json_path}...")
+    entries = json.loads(json_path.read_text(encoding="utf-8"))
+    logger.info(f"Loaded {len(entries)} entries from JSON")
+
+    import chromadb
+    from sentence_transformers import SentenceTransformer
+
+    logger.info(f"Loading embedding model: {EMBED_MODEL}")
+    model = SentenceTransformer(EMBED_MODEL)
+    logger.info("Embedding model loaded")
+
+    client = chromadb.PersistentClient(path=DB_PATH)
+
+    if force:
+        try:
+            client.delete_collection(name=COLLECTION)
+            logger.info("Deleted existing collection")
+        except Exception:
+            pass
+
+    collection = client.get_or_create_collection(
+        name=COLLECTION,
+        metadata={"hnsw:space": "cosine"},
+    )
+    logger.info(f"Collection '{COLLECTION}' ready")
+
+    batch_size = 50
+    total = len(entries)
+
+    for i in range(0, total, batch_size):
+        batch = entries[i : i + batch_size]
+
+        ids: list[str] = []
+        docs: list[str] = []
+        metas: list[dict[str, Any]] = []
+
+        for entry in batch:
+            url = entry.get("url", "")
+            name = entry.get("name", "").lower().strip().replace(" ", "").replace("()", "").replace("`", "")
+            entry_id = hashlib.md5((url + "|" + name).encode()).hexdigest()[:16]
+
+            doc_text = _build_document_text(entry)
+            meta = _flatten_metadata(entry)
+
+            ids.append(entry_id)
+            docs.append(doc_text)
+            metas.append(meta)
+
+        if docs:
+            try:
+                vecs = model.encode(docs, show_progress_bar=False)
+                embeddings = [v.tolist() for v in vecs]
+                collection.upsert(
+                    ids=ids,
+                    documents=docs,
+                    metadatas=metas,
+                    embeddings=embeddings,
+                )
+            except Exception as e:
+                logger.error(f"Embedding failed on batch {i // batch_size + 1}: {e}")
+                continue
+
+        if (i + batch_size) % 250 == 0 or i + batch_size >= total:
+            logger.info(f"Progress: {min(i + batch_size, total)}/{total} entries processed")
+
+    count = collection.count()
+    logger.info(f"ChromaDB build complete: {count} entries indexed at {DB_PATH}")
+    return count
+
+
+if __name__ == "__main__":
+    build_db(force=True)

qc_lean_mcp-1.2.0/core/caches.py

@@ -0,0 +1,110 @@
+"""
+core/caches.py
+All in-process LRU caches:
+  - Validation cache (code hash -> compiler result)
+  - File validation cache (path+mtime+size -> validation result)
+  - Query result cache (L1: ChromaDB query results)
+  - Codegen cache (template generation results)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from collections import OrderedDict
+from typing import Optional
+
+import xxhash
+from loguru import logger
+
+from core.config import VALIDATION_CACHE_MAX_SIZE, VALIDATION_CACHE_TTL
+
+_VALIDATION_CACHE: OrderedDict[str, tuple[str, float]] = OrderedDict()
+_VALIDATION_CACHE_LOCK = threading.Lock()
+
+
+def get_cached_validation(code: str) -> Optional[dict]:
+    h = xxhash.xxh64(code.encode()).hexdigest()
+    with _VALIDATION_CACHE_LOCK:
+        if h in _VALIDATION_CACHE:
+            result_str, ts = _VALIDATION_CACHE[h]
+            if time.time() - ts < VALIDATION_CACHE_TTL:
+                try:
+                    return json.loads(result_str)
+                except json.JSONDecodeError:
+                    logger.warning("Corrupt validation cache entry - evicting")
+                    del _VALIDATION_CACHE[h]
+    return None
+
+
+def set_cached_validation(code: str, result: str) -> None:
+    h = xxhash.xxh64(code.encode()).hexdigest()
+    with _VALIDATION_CACHE_LOCK:
+        _VALIDATION_CACHE[h] = (result, time.time())
+        _VALIDATION_CACHE.move_to_end(h)
+        while len(_VALIDATION_CACHE) > VALIDATION_CACHE_MAX_SIZE:
+            _VALIDATION_CACHE.popitem(last=False)
+
+
+_FILE_VALIDATION_CACHE: OrderedDict[tuple[str, int, int], tuple[str, float]] = OrderedDict()
+_FILE_VALIDATION_CACHE_LOCK = threading.Lock()
+_FILE_VALIDATION_CACHE_TTL = float(os.getenv("FILE_VALIDATION_CACHE_TTL", "1800"))
+_FILE_VALIDATION_CACHE_MAX = int(os.getenv("FILE_VALIDATION_CACHE_SIZE", "200"))
+
+
+def get_cached_file_validation(file_path: str, mtime_ns: int, file_size: int) -> Optional[str]:
+    key = (file_path, mtime_ns, file_size)
+    with _FILE_VALIDATION_CACHE_LOCK:
+        if key in _FILE_VALIDATION_CACHE:
+            result_str, ts = _FILE_VALIDATION_CACHE[key]
+            if time.time() - ts < _FILE_VALIDATION_CACHE_TTL:
+                logger.debug(f"File validation cache hit: {file_path}")
+                return result_str
+            else:
+                del _FILE_VALIDATION_CACHE[key]
+    return None
+
+
+def set_cached_file_validation(file_path: str, mtime_ns: int, file_size: int, result: str) -> None:
+    key = (file_path, mtime_ns, file_size)
+    with _FILE_VALIDATION_CACHE_LOCK:
+        _FILE_VALIDATION_CACHE[key] = (result, time.time())
+        _FILE_VALIDATION_CACHE.move_to_end(key)
+        while len(_FILE_VALIDATION_CACHE) > _FILE_VALIDATION_CACHE_MAX:
+            _FILE_VALIDATION_CACHE.popitem(last=False)
+
+
+_QUERY_RESULT_CACHE: OrderedDict[str, tuple[dict, float]] = OrderedDict()
+_QUERY_CACHE_LOCK = threading.Lock()
+_QUERY_CACHE_TTL = 600.0
+_QUERY_CACHE_MAX = 500
+
+
+_CODEGEN_CACHE: OrderedDict[str, tuple[str, float]] = OrderedDict()
+_CODEGEN_CACHE_LOCK = threading.Lock()
+_CODEGEN_CACHE_TTL = 600.0
+_CODEGEN_CACHE_MAX = 50
+
+
+def codegen_cache_key(name: str, description: str, inputs: str | None, overlay: bool) -> str:
+    return xxhash.xxh64(f"{name}|{description}|{inputs}|{overlay}".encode()).hexdigest()
+
+
+def get_codegen_cache(key: str) -> str | None:
+    with _CODEGEN_CACHE_LOCK:
+        if key in _CODEGEN_CACHE:
+            result, ts = _CODEGEN_CACHE[key]
+            if time.time() - ts < _CODEGEN_CACHE_TTL:
+                return result
+            del _CODEGEN_CACHE[key]
+    return None
+
+
+def set_codegen_cache(key: str, result: str) -> None:
+    with _CODEGEN_CACHE_LOCK:
+        _CODEGEN_CACHE[key] = (result, time.time())
+        _CODEGEN_CACHE.move_to_end(key)
+        while len(_CODEGEN_CACHE) > _CODEGEN_CACHE_MAX:
+            _CODEGEN_CACHE.popitem(last=False)