quant-research-mcp 0.1.0__tar.gz

quant_research_mcp-0.1.0/.dockerignore

@@ -0,0 +1,18 @@
+.git
+.github
+.venv
+venv
+__pycache__
+*.py[cod]
+*.egg-info
+.pytest_cache
+.ruff_cache
+.mypy_cache
+dist
+build
+*.mcpb
+.mcp.json
+.DS_Store
+reports
+evals
+tests

quant_research_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Test (offline)
+        run: uv run pytest tests/ -q
+
+      - name: Smoke — list the 13 tools
+        run: |
+          uv run python -c "import asyncio, server; \
+            names = sorted(t.name for t in asyncio.run(server.mcp.list_tools())); \
+            assert len(names) == 13, names; print(len(names), 'tools OK')"

quant_research_mcp-0.1.0/.github/workflows/docker.yml

@@ -0,0 +1,45 @@
+name: Docker
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-push:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Image metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

quant_research_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi-publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # PyPI Trusted Publishing (OIDC) — no token stored. Configure the trusted
+    # publisher for this repo + workflow + environment on PyPI first.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  bundle-and-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Pack Claude Desktop bundle (.mcpb)
+        run: npx -y @anthropic-ai/mcpb pack . quant-research-mcp.mcpb
+      - name: Create GitHub Release with artifacts
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*
+            quant-research-mcp.mcpb
+          generate_release_notes: true

quant_research_mcp-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+wheels/
+
+# Virtualenv / uv
+.venv/
+venv/
+env/
+
+# Test / lint caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Packaging artifacts
+*.mcpb
+
+# Per-machine MCP registration (contains an absolute path). Use
+# `make claude-add` / `make register`, or copy .mcp.json.example.
+.mcp.json
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/

quant_research_mcp-0.1.0/.mcp.json.example

@@ -0,0 +1,13 @@
+{
+  "//": "Copy to .mcp.json (gitignored). Path-free: runs straight from GitHub via uvx. After a PyPI release you can drop the --from git+... and use the published package, or `make register` for the local checkout form.",
+  "mcpServers": {
+    "quant_research": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/FlawlessByte/quant-research-mcp",
+        "quant-research-mcp"
+      ]
+    }
+  }
+}

quant_research_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing
+
+Thanks for your interest. This project packages paper-backed quantitative
+trading methods as MCP tools, plus a deterministic decision helper. Two hard
+rules keep it trustworthy:
+
+1. **No LLM, no subprocess, no network inside the decision logic.** The server
+   supplies reproducible math; the calling agent supplies judgement. `make check`
+   fails the build if it finds `subprocess` or `claude -p`.
+2. **Read-only.** Tools place no orders and persist nothing. Open positions are
+   passed in per call.
+
+## Dev setup
+
+```bash
+git clone https://github.com/FlawlessByte/quant-research-mcp
+cd quant-research-mcp
+make dev          # uv sync + ruff
+make check        # ruff + 40 offline tests + no-subprocess assertion
+make smoke        # list the 13 tools (no network)
+```
+
+Tests must stay **fully offline** — network is monkeypatched in `tests/`. New
+tests follow the same pattern (see `tests/conftest.py`).
+
+## Adding a paper-backed method
+
+The registry is built for this — one new module, one import line, nothing else
+changes:
+
+```python
+# quant_research_mcp/methods/my_paper.py
+from . import register
+from .base import TradingMethod, TradeSetup, DataRequirements
+
+def analyze(daily, session, context) -> TradeSetup:
+    ...  # compute signal, entry, stop, target
+
+register(TradingMethod(
+    key="my_paper_method",
+    name="My Method",
+    paper="Author et al., Title (Year)",
+    paper_url="https://arxiv.org/abs/...",
+    regime_applicability="TRENDING",
+    timeframe="swing",                 # intraday | swing | position
+    data=DataRequirements(daily_period="2y"),
+    description="One paragraph on the mechanics.",
+    analyze=analyze,
+))
+```
+
+Then add `from . import my_paper` to `quant_research_mcp/methods/__init__.py`.
+It now appears in `quant_list_methods` and runs via `quant_analyze_setup`. Add a
+trigger-logic test in `tests/test_methods.py` on synthetic data, and — if the
+method makes entry decisions — a deterministic Q&A in `evals/evaluation.xml`.
+
+## Before you open a PR
+
+- `make check` is green (ruff + tests + no-subprocess).
+- New behaviour has a test; new entry logic has an eval.
+- Commits use [Conventional Commits](https://www.conventionalcommits.org/)
+  (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`).
+- Cite the paper for any new method.
+
+## Not financial advice
+
+This is research tooling. Do not add anything that places orders, gives
+investment advice, or implies a guaranteed outcome.

quant_research_mcp-0.1.0/Dockerfile

@@ -0,0 +1,21 @@
+# Containerised stdio MCP server. Run with -i so the server can read stdin:
+#   docker run -i --rm ghcr.io/flawlessbyte/quant-research-mcp
+FROM python:3.12-slim
+
+# uv for fast, locked installs.
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=never
+
+WORKDIR /app
+
+# Install dependencies first (cached layer), then the project.
+COPY pyproject.toml uv.lock README.md ./
+COPY quant_research_mcp ./quant_research_mcp
+COPY server.py ./
+RUN uv sync --frozen --no-dev
+
+# stdio transport: the entry point talks MCP over stdin/stdout.
+ENTRYPOINT ["uv", "run", "--no-dev", "quant-research-mcp"]

quant_research_mcp-0.1.0/LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 FlawlessByte
+
+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.
+
+---
+
+ADDITIONAL NOTICE — NOT FINANCIAL ADVICE
+
+This software is research and educational tooling. It performs quantitative
+computation only and places no orders. Nothing it outputs is investment advice,
+a recommendation, or a solicitation to buy or sell any security. Market data may
+be delayed or inaccurate. Trading involves substantial risk of loss. You are
+solely responsible for any decision you make and any capital you risk. The
+authors accept no liability for trading losses or for any use of this software.

quant_research_mcp-0.1.0/Makefile

@@ -0,0 +1,88 @@
+# quant_research_mcp — common tasks. Run `make help` for the list.
+
+.DEFAULT_GOAL := help
+SHELL := /bin/bash
+
+# Absolute project dir so `make register` emits a portable client config.
+PROJECT_DIR := $(shell pwd)
+
+# GHCR image name (lowercase, per registry rules).
+IMAGE := ghcr.io/flawlessbyte/quant-research-mcp
+
+.PHONY: help install install-cli uninstall-cli dev run inspect smoke test check \
+        build docker-build mcpb clean register claude-add claude-remove
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'
+
+install: ## Create the venv and install dependencies (uv sync)
+	uv sync
+
+install-cli: ## Install the `quant-research-mcp` binary onto your PATH (uv tool)
+	# --reinstall --no-cache forces a fresh build so source edits ship even when
+	# the project version is unchanged (uv otherwise serves a cached wheel).
+	uv tool install --force --reinstall --no-cache .
+	@echo
+	@echo "Installed. Binary location:"
+	@command -v quant-research-mcp || { \
+		echo "  not on PATH yet — run: uv tool update-shell  (then restart your shell)"; \
+		echo "  or add $$(uv tool dir)/../bin to PATH"; }
+
+uninstall-cli: ## Remove the `quant-research-mcp` binary from your PATH
+	uv tool uninstall quant-research-mcp
+
+dev: ## Install plus dev extras (ruff) for linting
+	uv sync
+	uv add --dev ruff
+
+run: ## Run the MCP server over stdio
+	uv run python server.py
+
+inspect: ## Launch the MCP Inspector against the server
+	npx @modelcontextprotocol/inspector uv run python server.py
+
+smoke: ## Import the server and list its tools (no network)
+	uv run python -c "import asyncio, server; \
+		print('tools:', sorted(t.name for t in asyncio.run(server.mcp.list_tools())))"
+
+test: ## Run the pytest suite (no network needed)
+	uv run pytest tests/ -q
+
+check: ## Tests + lint + confirm no LLM/subprocess calls
+	uv run pytest tests/ -q
+	-uv run ruff check . 2>/dev/null || echo "ruff not installed; run 'make dev'"
+	@if grep -rniE 'subprocess|claude -p' --include='*.py' \
+		--exclude-dir=.venv --exclude-dir=__pycache__ . \
+		| grep -v 'no LLM, no network, no subprocess'; then \
+		echo "FAIL: LLM/subprocess reference found"; exit 1; \
+	else echo "OK: no LLM/subprocess calls"; fi
+
+register: ## Print the stdio MCP client config block for this project
+	@echo '{'
+	@echo '  "mcpServers": {'
+	@echo '    "quant_research": {'
+	@echo '      "command": "uv",'
+	@echo '      "args": ["run", "python", "server.py"],'
+	@echo '      "cwd": "$(PROJECT_DIR)"'
+	@echo '    }'
+	@echo '  }'
+	@echo '}'
+
+claude-add: ## Register this local clone with Claude Code (user scope)
+	claude mcp add quant_research --scope user -- uv run --directory $(PROJECT_DIR) python server.py
+
+claude-remove: ## Remove this server from Claude Code
+	claude mcp remove quant_research
+
+build: ## Build the sdist + wheel into dist/
+	uv build
+
+docker-build: ## Build the Docker image locally
+	docker build -t $(IMAGE) .
+
+mcpb: ## Pack a Claude Desktop .mcpb bundle
+	npx -y @anthropic-ai/mcpb pack . quant-research-mcp.mcpb
+
+clean: ## Remove caches and build artifacts
+	rm -rf .venv __pycache__ */__pycache__ */*/__pycache__ .ruff_cache dist build *.egg-info *.mcpb