futuresearch-mcp 0.6.0__tar.gz

futuresearch_mcp-0.6.0/.gitignore

@@ -0,0 +1,232 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+ .vscode/
+
+# MacOS
+.DS_Store
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+.history/
+.python-version
+
+# MCPB bundles
+*.mcpb
+
+# MCP registry tokens
+.mcpregistry_*
+
+# Claude Code local instructions
+CLAUDE.local.md
+worktrees/

futuresearch_mcp-0.6.0/.mcpbignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+*.egg-info/
+server/lib/
+server/venv/
+.mcpregistry_github_token
+.mcpregistry_registry_token
+tests/
+dist/
+.ruff_cache/

futuresearch_mcp-0.6.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: futuresearch-mcp
+Version: 0.6.0
+Summary: MCP server for futuresearch: a researcher for every row
+Requires-Python: >=3.12
+Requires-Dist: futuresearch>=0.6.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jsonschema>=4.0.0
+Requires-Dist: litellm>=1.50.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: pyjwt[crypto]>=2.8.0
+Requires-Dist: redis[hiredis]>=5.0.0
+Requires-Dist: sentry-sdk[starlette]>=2.0.0
+Requires-Dist: tabulate>=0.9.0
+Description-Content-Type: text/markdown
+
+# FutureSearch MCP Server
+
+> Most users don't need to run the MCP server locally. Use the hosted remote server at `https://mcp.futuresearch.ai/mcp` — it authenticates via OAuth, no API key needed. See the [setup guide](https://futuresearch.ai/docs). The instructions below are for self-hosted or advanced use cases where an API key is required.
+
+MCP (Model Context Protocol) server for [FutureSearch](https://futuresearch.ai): agent ops at spreadsheet scale.
+
+This server exposes FutureSearch's core operations as MCP tools, allowing LLM applications to classify, rank, dedupe, merge, forecast, and run agents on CSV files.
+
+**All tools operate on local CSV files.** Provide absolute file paths as input, and transformed results are written to new CSV files at your specified output path.
+
+## Installation
+
+The server requires a FutureSearch API key. Get one at [futuresearch.ai/api-key](https://futuresearch.ai/api-key) ($20 free credit).
+
+### Claude Desktop
+
+Download the latest `.mcpb` bundle from the [GitHub Releases](https://github.com/futuresearch/futuresearch-python/releases) page and double-click to install in Claude Desktop. You'll be prompted to enter your FutureSearch API key during setup. After installing the bundle, you can use FutureSearch from Chat, Cowork and Code within Claude Desktop.
+
+### Cursor
+Set the environment variable in your terminal shell before opening cursor. You may need to re-open cursor from your shell after this. Alternatively, hardcode the api key within cursor settings instead of the hard-coded `${env:FUTURESEARCH_API_KEY}`
+```bash
+export FUTURESEARCH_API_KEY=your_key_here
+```
+
+### Manual Config
+
+Either set the API key in your shell environment as mentioned above, or hardcode it directly in the config below. Environment variable interpolation may differ between MCP clients.
+
+```bash
+export FUTURESEARCH_API_KEY=your_key_here
+```
+
+Add this to your MCP config. If you have [uv](https://docs.astral.sh/uv/) installed:
+
+```json
+{
+  "mcpServers": {
+    "futuresearch": {
+      "command": "uvx",
+      "args": ["futuresearch-mcp"],
+      "env": {
+        "FUTURESEARCH_API_KEY": "${FUTURESEARCH_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Alternatively, install with pip (ideally in a venv) and use `"command": "futuresearch-mcp"` instead of uvx.
+
+## Workflow
+
+All operations follow an async pattern:
+
+1. **Start** - Call an operation tool (e.g., `futuresearch_agent`) to start a task. Returns immediately with a task ID and session URL.
+2. **Monitor** - Call `futuresearch_progress(task_id)` repeatedly to check status. The tool blocks ~12s to limit the polling rate.
+3. **Retrieve** - Once complete, call `futuresearch_results(task_id, output_path)` to save results to CSV.
+
+## Available Tools
+
+### futuresearch_rank
+
+Score and sort CSV rows based on qualitative criteria.
+
+```
+Parameters:
+- task: Natural language instructions for scoring a single row
+- input_csv: Absolute path to input CSV
+- field_name: Name of the score field to add
+- field_type: Type of the score field (float, int, str, bool)
+- ascending_order: Sort direction (default: true)
+- response_schema: (optional) JSON schema for custom response fields
+```
+
+Example: Rank leads by "likelihood to need data integration solutions"
+
+### futuresearch_dedupe
+
+Remove duplicate rows using semantic equivalence.
+
+```
+Parameters:
+- equivalence_relation: Natural language description of what makes rows duplicates
+- input_csv: Absolute path to input CSV
+```
+
+Example: Dedupe contacts where "same person even with name abbreviations or career changes"
+
+### futuresearch_merge
+
+Join two CSV files using intelligent entity matching (LEFT JOIN semantics).
+
+```
+Parameters:
+- task: Natural language description of how to match rows
+- left_csv: The table being enriched — all its rows are kept in the output
+- right_csv: The lookup/reference table — its columns are appended to matches; unmatched left rows get nulls
+- merge_on_left: (optional) Only set if you expect exact string matches on this column or want to draw agent attention to it. Fine to omit.
+- merge_on_right: (optional) Only set if you expect exact string matches on this column or want to draw agent attention to it. Fine to omit.
+- use_web_search: (optional) "auto" (default), "yes", or "no"
+- relationship_type: (optional) "many_to_one" (default) if multiple left rows can match one right row, "one_to_one" matches must be unique, "one_to_many" one left row can match multiple right rows, "many_to_many" multiple left rows can match multiple right rows. For one_to_many and many_to_many, multiple matches are joined with " | " in each added column.
+```
+
+Example: Match software products (left, enriched) to parent companies (right, lookup): Photoshop -> Adobe
+
+### futuresearch_classify
+
+Classify each row into one of the provided categories.
+
+```
+Parameters:
+- task: Natural language classification instructions
+- categories: Allowed categories (minimum 2)
+- classification_field: (optional) Output column name (default: "classification")
+- include_reasoning: (optional) Include reasoning column (default: false)
+```
+
+Example: Classify companies by GICS sector with categories ["Energy", "Financials", "Information Technology", ...]
+
+### futuresearch_forecast
+
+Forecast the probability of binary questions.
+
+```
+Parameters:
+- context: (optional) Batch-level context for all questions
+```
+
+Example: "Will the US Federal Reserve cut rates before July 2027?"
+
+### futuresearch_agent
+
+Run web research agents on each row of a CSV.
+
+```
+Parameters:
+- task: Natural language description of research task
+- input_csv: Absolute path to input CSV
+- response_schema: (optional) JSON schema for custom response fields
+```
+
+Example: "Find this company's latest funding round and lead investors"
+
+### futuresearch_progress
+
+Check progress of a running task.
+
+```
+Parameters:
+- task_id: The task ID returned by an operation tool
+```
+
+Blocks ~12s before returning status. Call repeatedly until task completes.
+
+### futuresearch_results
+
+Retrieve and save results from a completed task.
+
+```
+Parameters:
+- task_id: The task ID of the completed task
+- output_path: Full absolute path to output CSV file (must end in .csv)
+```
+
+Only call after `futuresearch_progress` reports status "completed".
+
+## Development
+
+```bash
+cd futuresearch-mcp
+uv sync
+uv run pytest
+```
+For MCP [registry publishing](https://modelcontextprotocol.info/tools/registry/publishing/#package-deployment):
+
+mcp-name: io.github.futuresearch/futuresearch-mcp
+
+
+## License
+
+MIT - See [LICENSE.txt](../LICENSE.txt)

futuresearch_mcp-0.6.0/README.md

@@ -0,0 +1,181 @@
+# FutureSearch MCP Server
+
+> Most users don't need to run the MCP server locally. Use the hosted remote server at `https://mcp.futuresearch.ai/mcp` — it authenticates via OAuth, no API key needed. See the [setup guide](https://futuresearch.ai/docs). The instructions below are for self-hosted or advanced use cases where an API key is required.
+
+MCP (Model Context Protocol) server for [FutureSearch](https://futuresearch.ai): agent ops at spreadsheet scale.
+
+This server exposes FutureSearch's core operations as MCP tools, allowing LLM applications to classify, rank, dedupe, merge, forecast, and run agents on CSV files.
+
+**All tools operate on local CSV files.** Provide absolute file paths as input, and transformed results are written to new CSV files at your specified output path.
+
+## Installation
+
+The server requires a FutureSearch API key. Get one at [futuresearch.ai/api-key](https://futuresearch.ai/api-key) ($20 free credit).
+
+### Claude Desktop
+
+Download the latest `.mcpb` bundle from the [GitHub Releases](https://github.com/futuresearch/futuresearch-python/releases) page and double-click to install in Claude Desktop. You'll be prompted to enter your FutureSearch API key during setup. After installing the bundle, you can use FutureSearch from Chat, Cowork and Code within Claude Desktop.
+
+### Cursor
+Set the environment variable in your terminal shell before opening cursor. You may need to re-open cursor from your shell after this. Alternatively, hardcode the api key within cursor settings instead of the hard-coded `${env:FUTURESEARCH_API_KEY}`
+```bash
+export FUTURESEARCH_API_KEY=your_key_here
+```
+
+### Manual Config
+
+Either set the API key in your shell environment as mentioned above, or hardcode it directly in the config below. Environment variable interpolation may differ between MCP clients.
+
+```bash
+export FUTURESEARCH_API_KEY=your_key_here
+```
+
+Add this to your MCP config. If you have [uv](https://docs.astral.sh/uv/) installed:
+
+```json
+{
+  "mcpServers": {
+    "futuresearch": {
+      "command": "uvx",
+      "args": ["futuresearch-mcp"],
+      "env": {
+        "FUTURESEARCH_API_KEY": "${FUTURESEARCH_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Alternatively, install with pip (ideally in a venv) and use `"command": "futuresearch-mcp"` instead of uvx.
+
+## Workflow
+
+All operations follow an async pattern:
+
+1. **Start** - Call an operation tool (e.g., `futuresearch_agent`) to start a task. Returns immediately with a task ID and session URL.
+2. **Monitor** - Call `futuresearch_progress(task_id)` repeatedly to check status. The tool blocks ~12s to limit the polling rate.
+3. **Retrieve** - Once complete, call `futuresearch_results(task_id, output_path)` to save results to CSV.
+
+## Available Tools
+
+### futuresearch_rank
+
+Score and sort CSV rows based on qualitative criteria.
+
+```
+Parameters:
+- task: Natural language instructions for scoring a single row
+- input_csv: Absolute path to input CSV
+- field_name: Name of the score field to add
+- field_type: Type of the score field (float, int, str, bool)
+- ascending_order: Sort direction (default: true)
+- response_schema: (optional) JSON schema for custom response fields
+```
+
+Example: Rank leads by "likelihood to need data integration solutions"
+
+### futuresearch_dedupe
+
+Remove duplicate rows using semantic equivalence.
+
+```
+Parameters:
+- equivalence_relation: Natural language description of what makes rows duplicates
+- input_csv: Absolute path to input CSV
+```
+
+Example: Dedupe contacts where "same person even with name abbreviations or career changes"
+
+### futuresearch_merge
+
+Join two CSV files using intelligent entity matching (LEFT JOIN semantics).
+
+```
+Parameters:
+- task: Natural language description of how to match rows
+- left_csv: The table being enriched — all its rows are kept in the output
+- right_csv: The lookup/reference table — its columns are appended to matches; unmatched left rows get nulls
+- merge_on_left: (optional) Only set if you expect exact string matches on this column or want to draw agent attention to it. Fine to omit.
+- merge_on_right: (optional) Only set if you expect exact string matches on this column or want to draw agent attention to it. Fine to omit.
+- use_web_search: (optional) "auto" (default), "yes", or "no"
+- relationship_type: (optional) "many_to_one" (default) if multiple left rows can match one right row, "one_to_one" matches must be unique, "one_to_many" one left row can match multiple right rows, "many_to_many" multiple left rows can match multiple right rows. For one_to_many and many_to_many, multiple matches are joined with " | " in each added column.
+```
+
+Example: Match software products (left, enriched) to parent companies (right, lookup): Photoshop -> Adobe
+
+### futuresearch_classify
+
+Classify each row into one of the provided categories.
+
+```
+Parameters:
+- task: Natural language classification instructions
+- categories: Allowed categories (minimum 2)
+- classification_field: (optional) Output column name (default: "classification")
+- include_reasoning: (optional) Include reasoning column (default: false)
+```
+
+Example: Classify companies by GICS sector with categories ["Energy", "Financials", "Information Technology", ...]
+
+### futuresearch_forecast
+
+Forecast the probability of binary questions.
+
+```
+Parameters:
+- context: (optional) Batch-level context for all questions
+```
+
+Example: "Will the US Federal Reserve cut rates before July 2027?"
+
+### futuresearch_agent
+
+Run web research agents on each row of a CSV.
+
+```
+Parameters:
+- task: Natural language description of research task
+- input_csv: Absolute path to input CSV
+- response_schema: (optional) JSON schema for custom response fields
+```
+
+Example: "Find this company's latest funding round and lead investors"
+
+### futuresearch_progress
+
+Check progress of a running task.
+
+```
+Parameters:
+- task_id: The task ID returned by an operation tool
+```
+
+Blocks ~12s before returning status. Call repeatedly until task completes.
+
+### futuresearch_results
+
+Retrieve and save results from a completed task.
+
+```
+Parameters:
+- task_id: The task ID of the completed task
+- output_path: Full absolute path to output CSV file (must end in .csv)
+```
+
+Only call after `futuresearch_progress` reports status "completed".
+
+## Development
+
+```bash
+cd futuresearch-mcp
+uv sync
+uv run pytest
+```
+For MCP [registry publishing](https://modelcontextprotocol.info/tools/registry/publishing/#package-deployment):
+
+mcp-name: io.github.futuresearch/futuresearch-mcp
+
+
+## License
+
+MIT - See [LICENSE.txt](../LICENSE.txt)

futuresearch_mcp-0.6.0/deploy/.dockerignore

@@ -0,0 +1,15 @@
+.git
+.github
+.venv
+__pycache__
+*.pyc
+.env
+*.env
+!.env.example
+.claude/
+.vscode/
+*.egg-info
+dist/
+build/
+node_modules/
+docs-site/

futuresearch_mcp-0.6.0/deploy/.env.example

@@ -0,0 +1,8 @@
+FUTURESEARCH_API_KEY=sk-cho-your-api-key-here
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_KEY=sb_publishable_your-anon-key-here
+MCP_SERVER_URL=https://your-tunnel-url.example.com
+REDIS_PASSWORD=change-me-to-a-strong-random-password
+
+# Legacy env vars (still supported for backwards compatibility):
+# EVERYROW_API_KEY=sk-cho-your-api-key-here

futuresearch_mcp-0.6.0/deploy/Dockerfile

@@ -0,0 +1,36 @@
+# Stage 1: Build Python environment with uv
+FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim AS build
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+WORKDIR /app
+
+# Copy workspace root pyproject + lock + README, then each package
+COPY --link pyproject.toml uv.lock README.md ./
+COPY --link src/ ./src/
+COPY --link everyrow-mcp/pyproject.toml everyrow-mcp/README.md ./everyrow-mcp/
+COPY --link everyrow-mcp/src/ ./everyrow-mcp/src/
+
+# Install everyrow-mcp and its dependencies (includes workspace everyrow package)
+RUN uv sync --package everyrow-mcp --no-dev --no-sources --no-editable
+
+# Stage 2: Slim runtime
+FROM python:3.13-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+RUN groupadd -r -g 10000 mcp && useradd -r -u 10000 -g mcp -d /app -s /sbin/nologin mcp
+
+ENV PATH="/app/.venv/bin:$PATH"
+EXPOSE 8000
+
+WORKDIR /app
+COPY --link --from=build /app/.venv .venv
+RUN chown -R mcp:mcp /app
+
+USER mcp
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"
+
+CMD ["everyrow-mcp", "--http", "--port", "8000", "--host", "0.0.0.0"]

futuresearch_mcp-0.6.0/deploy/chart/.gitignore

@@ -0,0 +1,4 @@
+/secrets.yaml
+/values.secrets.yaml
+/values.secrets.staging.yaml
+/secrets.staging.yaml

futuresearch_mcp-0.6.0/deploy/chart/.sops.yaml

@@ -0,0 +1,2 @@
+creation_rules:
+    - gcp_kms: projects/varuna-400921/locations/global/keyRings/sops/cryptoKeys/sops-key