dataquery-sdk 1.2.5__tar.gz → 1.2.7__tar.gz

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/CHANGELOG.md

@@ -54,6 +54,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.2.4] - 2026-08-12
 - MCP: `mcp-connect` accepts `--client-id`, `--client-secret` and `--bearer-token` and exports them into the `DATAQUERY_*` environment of the process, so the MCP bridge and the SDK share one credential set instead of each needing its own setup
 ## [1.2.5] - 2026-08-21
-- MCP: `mcp-connect --url` is now optional 
- 
- 
+- MCP: `mcp-connect --url` is now optional
+## [1.2.6] - 2026-09-24
+- Bug fixes
+- MCP: capped the `mcp` extra to `fastmcp>=2.14,<4` — fastmcp 4.x repackages onto `httpx2` and drops `FastMCP.as_proxy()`, which broke `mcp-connect`; installs now resolve to the 3.x line
+## [1.2.7] - 2026-09-25
+- MCP: new `dataquery mcp-install` one-time setup — saves your credentials to `~/.dataquery/.env` (prompting on a terminal, the secret unechoed) and adds a secret-free server running this environment's `mcp-connect` to Claude Desktop (default) or, with `--app`, Claude Code (user scope), ChatGPT desktop / Codex (`~/.codex/config.toml`), Cursor or VS Code, or to any `mcpServers` JSON file (`--config-file`); re-running updates it

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataquery-sdk
-Version: 1.2.5
+Version: 1.2.7
 Summary: Python SDK for DATAQUERY Data API - Query, download, and check availability of economic data files
 Author-email: DATAQUERY SDK Team <dataquery_support@jpmorgan.com>
 Project-URL: Homepage, https://github.com/jpmorganchase/dataquery-sdk
@@ -50,7 +50,7 @@ Requires-Dist: pymdown-extensions>=11.0.0; extra == "docs"
 Provides-Extra: pandas
 Requires-Dist: pandas>=2.0.0; extra == "pandas"
 Provides-Extra: mcp
-Requires-Dist: fastmcp>=2.14; extra == "mcp"
+Requires-Dist: fastmcp<4,>=2.14; extra == "mcp"
 Provides-Extra: all
 Requires-Dist: pytest>=7.0.0; extra == "all"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "all"
@@ -63,7 +63,7 @@ Requires-Dist: mkdocs-material>=9.0.0; extra == "all"
 Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "all"
 Requires-Dist: mike>=1.1.0; extra == "all"
 Requires-Dist: pandas>=2.0.0; extra == "all"
-Requires-Dist: fastmcp>=2.14; extra == "all"
+Requires-Dist: fastmcp<4,>=2.14; extra == "all"
 Requires-Dist: pip-audit>=2.7.0; extra == "all"
 Requires-Dist: build>=1.3.0; extra == "all"
 Requires-Dist: urllib3>=2.7.0; extra == "all"
@@ -467,8 +467,39 @@ pip install "dataquery-sdk[mcp]"
 
 ### Wire it into an MCP client
 
-Add the server to your client's MCP config (`claude_desktop_config.json`,
-`.mcp.json`, or the equivalent for your host):
+**One-time setup (recommended).** Install, then run `mcp-install` once:
+
+```bash
+pip install "dataquery-sdk[mcp]"
+dataquery mcp-install                  # Claude Desktop (the default)
+dataquery mcp-install --app <app>      # one of the apps below
+dataquery mcp-install --config-file ~/.some-app/mcp.json   # any other app with an mcpServers JSON file
+```
+
+| `--app` | Where the server goes |
+|---|---|
+| `claude-desktop` | Claude Desktop's `claude_desktop_config.json` |
+| `claude-code` | Claude Code, user scope (via `claude mcp add-json`) |
+| `chatgpt` | `~/.codex/config.toml`, which the ChatGPT desktop app shares with the Codex CLI and IDE extension; ChatGPT on the web can't run local servers |
+| `cursor` | `~/.cursor/mcp.json` |
+| `vscode` | VS Code's user-profile `mcp.json` (default profile) |
+
+It prompts for your client ID and secret (the secret without echo) and saves
+them to `~/.dataquery/.env`, owner-only (see [Credentials](#credentials)). It
+then adds a `dataquery` server to the app's user config. The entry runs this
+environment's `dataquery mcp-connect` by absolute path, because GUI apps don't
+see your shell's `PATH`, and it contains no secrets. Other servers and settings
+in the file are kept. Restart the app to load it.
+
+- Re-run it any time to update the credentials or the entry.
+- `--client-id`/`--client-secret` or `--bearer-token` skip the prompt, but flags
+  are visible in the process list.
+- `--url` and `--name` register another environment alongside the first.
+- Run it from an environment you keep (pip or pipx), not a throwaway `uvx` one,
+  because the entry points at that environment's executable.
+
+**Manual setup.** Or add the server to your client's MCP config yourself
+(`claude_desktop_config.json`, `.mcp.json`, or the equivalent for your host):
 
 ```json
 {
@@ -639,6 +670,43 @@ async with DataQuery(client_id="...", client_secret="...", timeout=60.0) as dq:
     ...
 ```
 
+### Custom request headers
+
+Headers are configured per client, on `ClientConfig` or as `DataQuery(...)`
+kwargs, and are never read from the environment, so several clients in one
+process can identify themselves differently. They are sent on every DataQuery
+API request (JSON, file and SSE), but not on the OAuth token request.
+
+```python
+config = ClientConfig(
+    client_id="...",
+    client_secret="...",
+    custom_headers={
+        "X-User-Agent": "RiskEngine/2.1",
+        "X-Team": "rates",
+        "X-Request-Source": "nightly-batch",
+    },
+)
+
+async with DataQuery(config) as dq:
+    ...
+
+# Or as kwargs:
+async with DataQuery(custom_headers={"X-User-Agent": "RiskEngine/2.1"}) as dq:
+    ...
+```
+
+- A custom header replaces an SDK default of the same name (e.g. `User-Agent`),
+  but never `Authorization`, which comes from `client_id`/`client_secret` or
+  `bearer_token`, and never the SSE stream's `Accept` / `Last-Event-ID`.
+- Invalid headers (a bad name, CR/LF in a value, a name repeated in another
+  case, `Authorization`) raise `ConfigurationError` before the first request.
+  The error names the header but never shows its value.
+- Kwarg overrides are written onto the `ClientConfig` you pass in, so give each
+  client its own config instead of sharing one.
+- The `x_user_agent` option and `DATAQUERY_X_USER_AGENT` are gone; send
+  `X-User-Agent` through `custom_headers` like any other header.
+
 ## Logging
 
 The SDK logs through [structlog](https://www.structlog.org/) and emits

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/README.md

@@ -395,8 +395,39 @@ pip install "dataquery-sdk[mcp]"
 
 ### Wire it into an MCP client
 
-Add the server to your client's MCP config (`claude_desktop_config.json`,
-`.mcp.json`, or the equivalent for your host):
+**One-time setup (recommended).** Install, then run `mcp-install` once:
+
+```bash
+pip install "dataquery-sdk[mcp]"
+dataquery mcp-install                  # Claude Desktop (the default)
+dataquery mcp-install --app <app>      # one of the apps below
+dataquery mcp-install --config-file ~/.some-app/mcp.json   # any other app with an mcpServers JSON file
+```
+
+| `--app` | Where the server goes |
+|---|---|
+| `claude-desktop` | Claude Desktop's `claude_desktop_config.json` |
+| `claude-code` | Claude Code, user scope (via `claude mcp add-json`) |
+| `chatgpt` | `~/.codex/config.toml`, which the ChatGPT desktop app shares with the Codex CLI and IDE extension; ChatGPT on the web can't run local servers |
+| `cursor` | `~/.cursor/mcp.json` |
+| `vscode` | VS Code's user-profile `mcp.json` (default profile) |
+
+It prompts for your client ID and secret (the secret without echo) and saves
+them to `~/.dataquery/.env`, owner-only (see [Credentials](#credentials)). It
+then adds a `dataquery` server to the app's user config. The entry runs this
+environment's `dataquery mcp-connect` by absolute path, because GUI apps don't
+see your shell's `PATH`, and it contains no secrets. Other servers and settings
+in the file are kept. Restart the app to load it.
+
+- Re-run it any time to update the credentials or the entry.
+- `--client-id`/`--client-secret` or `--bearer-token` skip the prompt, but flags
+  are visible in the process list.
+- `--url` and `--name` register another environment alongside the first.
+- Run it from an environment you keep (pip or pipx), not a throwaway `uvx` one,
+  because the entry points at that environment's executable.
+
+**Manual setup.** Or add the server to your client's MCP config yourself
+(`claude_desktop_config.json`, `.mcp.json`, or the equivalent for your host):
 
 ```json
 {
@@ -567,6 +598,43 @@ async with DataQuery(client_id="...", client_secret="...", timeout=60.0) as dq:
     ...
 ```
 
+### Custom request headers
+
+Headers are configured per client, on `ClientConfig` or as `DataQuery(...)`
+kwargs, and are never read from the environment, so several clients in one
+process can identify themselves differently. They are sent on every DataQuery
+API request (JSON, file and SSE), but not on the OAuth token request.
+
+```python
+config = ClientConfig(
+    client_id="...",
+    client_secret="...",
+    custom_headers={
+        "X-User-Agent": "RiskEngine/2.1",
+        "X-Team": "rates",
+        "X-Request-Source": "nightly-batch",
+    },
+)
+
+async with DataQuery(config) as dq:
+    ...
+
+# Or as kwargs:
+async with DataQuery(custom_headers={"X-User-Agent": "RiskEngine/2.1"}) as dq:
+    ...
+```
+
+- A custom header replaces an SDK default of the same name (e.g. `User-Agent`),
+  but never `Authorization`, which comes from `client_id`/`client_secret` or
+  `bearer_token`, and never the SSE stream's `Accept` / `Last-Event-ID`.
+- Invalid headers (a bad name, CR/LF in a value, a name repeated in another
+  case, `Authorization`) raise `ConfigurationError` before the first request.
+  The error names the header but never shows its value.
+- Kwarg overrides are written onto the `ClientConfig` you pass in, so give each
+  client its own config instead of sharing one.
+- The `x_user_agent` option and `DATAQUERY_X_USER_AGENT` are gone; send
+  `X-User-Agent` through `custom_headers` like any other header.
+
 ## Logging
 
 The SDK logs through [structlog](https://www.structlog.org/) and emits

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/dataquery/__init__.py

@@ -1,6 +1,6 @@
 """DATAQUERY SDK - Python SDK for DATAQUERY Data API."""
 
-__version__ = "1.2.5"
+__version__ = "1.2.7"
 __author__ = "DATAQUERY SDK Team"
 __email__ = "dataquery_support@jpmorgan.com"
 __license__ = "MIT"

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/dataquery/cli.py

@@ -2,6 +2,8 @@
 
 import argparse
 import asyncio
+import getpass
+import importlib.util
 import json
 import os
 import sys
@@ -139,6 +141,44 @@ def _save_mcp_credentials(keys: List[str]) -> None:
     print(f"Saved {saved} to {env_file} (owner-only)", file=sys.stderr)
 
 
+def _has_mcp_credentials(keys: List[str]) -> bool:
+    """A bearer token, or a complete OAuth client ID + secret pair."""
+    return "BEARER_TOKEN" in keys or {"CLIENT_ID", "CLIENT_SECRET"} <= set(keys)
+
+
+def _mcp_extra_installed() -> bool:
+    return importlib.util.find_spec("fastmcp") is not None
+
+
+# `mcp-install --app` targets: the JSON-config apps, plus Claude Code (its CLI) and ChatGPT (the Codex TOML).
+MCP_INSTALL_APPS = ("claude-desktop", "claude-code", "chatgpt", "cursor", "vscode")
+
+
+def _mcp_server_name(value: str) -> str:
+    from dataquery.mcp_install import SERVER_NAME_RE
+
+    if not SERVER_NAME_RE.fullmatch(value):
+        raise argparse.ArgumentTypeError(f"invalid server name {value!r}: use letters, digits, '-' and '_' only")
+    return value
+
+
+def _prompt_for_mcp_credentials() -> None:
+    """On a terminal, ask for whichever OAuth client credential is still missing (the secret unechoed)."""
+    from dataquery.config import EnvConfig
+
+    if not sys.stdin.isatty():
+        return
+    for key, label, ask in (
+        ("CLIENT_ID", "DataQuery client ID: ", input),
+        ("CLIENT_SECRET", "DataQuery client secret: ", getpass.getpass),
+    ):
+        env_key = f"{EnvConfig.PREFIX}{key}"
+        if not os.environ.get(env_key):
+            value = ask(label).strip()
+            if value:
+                os.environ[env_key] = value
+
+
 def create_parser() -> argparse.ArgumentParser:
     """Create the top-level CLI parser with subcommands."""
     parser = argparse.ArgumentParser(description="Command Line Interface for the DataQuery SDK")
@@ -390,6 +430,47 @@ def create_parser() -> argparse.ArgumentParser:
         "needs no environment variables",
     )
 
+    p_install = subparsers.add_parser(
+        "mcp-install",
+        help="One-time MCP setup: save your credentials and add the DataQuery server to your MCP app",
+        description=(
+            "Save your DataQuery credentials to ~/.dataquery/.env (owner-only) and add a\n"
+            "server that runs this environment's `dataquery mcp-connect` to your MCP\n"
+            "app's user config. No secrets go into that config. Missing credentials are\n"
+            "prompted for on a terminal, the secret without echo. Re-run any time to\n"
+            "update the credentials or the entry."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    target = p_install.add_mutually_exclusive_group()
+    target.add_argument(
+        "--app",
+        choices=MCP_INSTALL_APPS,
+        default="claude-desktop",
+        help="MCP app to configure (default: claude-desktop); chatgpt is the ChatGPT desktop app, "
+        "whose config the Codex CLI and IDE extension share",
+    )
+    target.add_argument(
+        "--config-file",
+        type=Path,
+        default=None,
+        help="Add the server to this mcpServers JSON file instead, for any other app",
+    )
+    p_install.add_argument(
+        "--name",
+        type=_mcp_server_name,
+        default="dataquery",
+        help="Server name in the MCP config (default: dataquery)",
+    )
+    p_install.add_argument("--url", default=None, help="MCP endpoint for mcp-connect (default: the PROD endpoint)")
+    p_install.add_argument("--client-id", default=None, help="OAuth client ID (prompted for when missing)")
+    p_install.add_argument(
+        "--client-secret",
+        default=None,
+        help="OAuth client secret; visible in the process list, so prefer the prompt",
+    )
+    p_install.add_argument("--bearer-token", default=None, help="Use a bearer token instead of OAuth")
+
     return parser
 
 
@@ -874,6 +955,64 @@ async def cmd_mcp_connect(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_mcp_install(args: argparse.Namespace) -> int:
+    """Save the credentials once and add the DataQuery MCP server to an MCP app's user config."""
+    from dataquery import mcp_install
+    from dataquery.config import EnvConfig
+    from dataquery.types.exceptions import ConfigurationError
+
+    if not _mcp_extra_installed():
+        print(
+            "The MCP bridge needs the 'mcp' extra. Install it, then re-run:\n    pip install 'dataquery-sdk[mcp]'",
+            file=sys.stderr,
+        )
+        return 1
+
+    if getattr(args, "env_file", None):
+        EnvConfig.load_env_file(Path(args.env_file))
+    # Already-saved credentials count, so re-running only refreshes the entry.
+    EnvConfig.load_user_env_file()
+    keys = _export_mcp_credentials(args)
+    if not _has_mcp_credentials(keys):
+        _prompt_for_mcp_credentials()
+        keys = _export_mcp_credentials(args)
+    if not _has_mcp_credentials(keys):
+        print(
+            "No credentials: pass --client-id and --client-secret (or --bearer-token), set "
+            "DATAQUERY_CLIENT_ID and DATAQUERY_CLIENT_SECRET, or run in a terminal to be prompted.",
+            file=sys.stderr,
+        )
+        return 1
+
+    entry = mcp_install.server_entry(args.url)
+    try:
+        # Saved first: an entry without credentials behind it would fail on every launch.
+        env_file = EnvConfig.save_user_env({key: os.environ.get(f"{EnvConfig.PREFIX}{key}") for key in keys})
+        print(f"Saved {', '.join(f'{EnvConfig.PREFIX}{key}' for key in keys)} to {env_file} (owner-only)")
+        if args.config_file is not None:
+            replaced = mcp_install.add_to_config_file(args.config_file, args.name, entry)
+            print(f"{'Updated' if replaced else 'Added'} '{args.name}' in {args.config_file}")
+            print("Restart your MCP app to load it.")
+        elif args.app == "claude-code":
+            mcp_install.add_to_claude_code(args.name, entry)
+            print(f"Added '{args.name}' to Claude Code (user scope); check it with: claude mcp list")
+        elif args.app == "chatgpt":
+            path, replaced = mcp_install.add_to_codex(args.name, entry)
+            print(f"{'Updated' if replaced else 'Added'} '{args.name}' in {path}")
+            print("Restart the ChatGPT desktop app (or Codex) to load it; ChatGPT on the web can't run local servers.")
+        else:
+            app = mcp_install.JSON_APPS[args.app]
+            path, replaced = app.add(args.name, entry)
+            print(f"{'Updated' if replaced else 'Added'} '{args.name}' in {path}")
+            print(f"Restart {app.label} to load it.")
+    except (ConfigurationError, OSError) as exc:
+        print(f"mcp-install: {exc}", file=sys.stderr)
+        return 1
+    print("The server runs:", " ".join([entry["command"], *entry["args"]]))
+    print("No secrets were written to the MCP config; mcp-connect reads them from the saved file.")
+    return 0
+
+
 def main_sync(ns: argparse.Namespace) -> int:
     if ns.command == "config":
         if ns.config_command == "show":
@@ -919,6 +1058,8 @@ def main() -> int:
         return asyncio.run(cmd_auth_test(args))
     if args.command == "function-help":
         return cmd_function_help(args)
+    if args.command == "mcp-install":
+        return cmd_mcp_install(args)
 
     handler = _ASYNC_COMMANDS.get(args.command)
     if handler is None:

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/dataquery/config/env.py

@@ -21,6 +21,13 @@ _DEFAULT_OVERRIDES: Dict[str, str] = {
     "TOKEN_STORAGE_DIR": ".tokens",
 }
 
+# Per-client settings: set on ClientConfig (or passed to DataQuery), never read
+# from the environment, so clients in one process can send different headers.
+_CLIENT_ONLY_FIELDS = frozenset({"custom_headers"})
+
+# ClientConfig fields that map to a DATAQUERY_* env var.
+_ENV_FIELDS = {name: field for name, field in ClientConfig.model_fields.items() if name not in _CLIENT_ONLY_FIELDS}
+
 _SENSITIVE_FIELDS = frozenset(
     {
         "client_id",
@@ -80,7 +87,7 @@ def _unwrap_optional(annotation: Any) -> Any:
 def _build_defaults() -> Dict[str, Optional[str]]:
     """Compute the ``EnvConfig.DEFAULTS`` table from the model."""
     defaults: Dict[str, Optional[str]] = {}
-    for field_name, field in ClientConfig.model_fields.items():
+    for field_name, field in _ENV_FIELDS.items():
         env_key = _env_name_for(field_name)
         if field.default is PydanticUndefined or field.default is None:
             defaults[env_key] = None
@@ -244,7 +251,7 @@ class EnvConfig:
             raise ConfigurationError(f"{cls.PREFIX}BASE_URL environment variable is required")
 
         kwargs: Dict[str, Any] = {}
-        for field_name, field in ClientConfig.model_fields.items():
+        for field_name, field in _ENV_FIELDS.items():
             kwargs[field_name] = cls._read_field(field_name, field)
 
         if kwargs.get("oauth_enabled") and not kwargs.get("oauth_token_url"):
@@ -352,6 +359,10 @@ class EnvConfig:
             errors.append("REQUESTS_PER_MINUTE must be positive")
         if config.burst_capacity <= 0:
             errors.append("BURST_CAPACITY must be positive")
+        try:
+            config.get_custom_headers()
+        except ConfigurationError as exc:
+            errors.append(str(exc))
 
         if errors:
             raise ConfigurationError(f"Configuration validation failed: {'; '.join(errors)}")
@@ -370,7 +381,7 @@ class EnvConfig:
             "# Defaults shown are the values used when the variable is unset.",
             "",
         ]
-        for field_name, field in ClientConfig.model_fields.items():
+        for field_name, field in _ENV_FIELDS.items():
             env_key = _env_name_for(field_name)
             default = cls.DEFAULTS.get(env_key)
             description = (field.description or "").strip()

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/dataquery/constants/__init__.py

@@ -34,7 +34,7 @@ from .download import (
     SMALL_FILE_THRESHOLD,
     TEMP_SUFFIX,
 )
-from .rate_limit import RATE_LIMIT_MIN_WAIT_SECONDS
+from .rate_limit import RATE_LIMIT_MIN_WAIT_SECONDS, RATE_LIMIT_POLL_INTERVAL_SECONDS
 from .sse import SSE_HEALTHY_CONNECTION_SECONDS, SSE_MAX_AUTH_RETRIES, SSE_READ_BUFSIZE
 
 __all__ = [
@@ -67,6 +67,7 @@ __all__ = [
     "SMALL_FILE_THRESHOLD",
     "TEMP_SUFFIX",
     "RATE_LIMIT_MIN_WAIT_SECONDS",
+    "RATE_LIMIT_POLL_INTERVAL_SECONDS",
     "SSE_HEALTHY_CONNECTION_SECONDS",
     "SSE_MAX_AUTH_RETRIES",
     "SSE_READ_BUFSIZE",

dataquery_sdk-1.2.7/dataquery/constants/rate_limit.py

@@ -0,0 +1,9 @@
+"""Rate-limiter tunables."""
+
+from __future__ import annotations
+
+RATE_LIMIT_MIN_WAIT_SECONDS = 0.2
+
+# Upper bound on a single sleep while waiting for a token. The lock is not held
+# across the sleep, so waiters re-check the bucket at least this often.
+RATE_LIMIT_POLL_INTERVAL_SECONDS = 0.1

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/dataquery/core/client.py

@@ -52,6 +52,7 @@ from ..types.models import (
     GroupList,
     InstrumentsResponse,
     TimeSeriesResponse,
+    merge_headers,
 )
 from ..utils import (
     format_file_size,
@@ -260,6 +261,8 @@ class DataQueryClient(
     async def connect(self):
         """Initialize HTTP session with optimized configuration."""
         if self.session is None:
+            # Resolved first: a bad custom header fails here, before any connector is opened.
+            custom_headers = self.config.get_custom_headers()
             timeout = aiohttp.ClientTimeout(total=self.config.timeout, connect=300.0, sock_read=self.config.timeout)
 
             connector = aiohttp.TCPConnector(
@@ -286,12 +289,16 @@ class DataQueryClient(
             session_kwargs = {
                 "timeout": timeout,
                 "connector": connector,
-                "headers": {
-                    "User-Agent": f"DATAQUERY-SDK/{version}",
-                    "Connection": "keep-alive",
-                    "Accept-Encoding": "gzip, deflate",
-                    **self.config.get_custom_headers(),
-                },
+                # Custom headers layer over these defaults, so a client may replace e.g. User-Agent;
+                # per-request headers (Authorization, Range) still win over both.
+                "headers": merge_headers(
+                    {
+                        "User-Agent": f"DATAQUERY-SDK/{version}",
+                        "Connection": "keep-alive",
+                        "Accept-Encoding": "gzip, deflate",
+                    },
+                    custom_headers,
+                ),
                 "auto_decompress": True,
                 "raise_for_status": False,
             }

dataquery_sdk-1.2.7/dataquery/mcp_install.py

@@ -0,0 +1,198 @@
+"""One-time setup: register ``dataquery mcp-connect`` with an MCP client app."""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from .types.exceptions import ConfigurationError
+
+# Server names this installer writes: safe as a JSON key, a TOML bare key and a CLI argument.
+SERVER_NAME_RE = re.compile(r"[A-Za-z0-9_-]+")
+
+_CLAUDE_CLI_TIMEOUT = 60.0
+
+
+def dataquery_command() -> List[str]:
+    """The absolute command that runs this environment's ``dataquery`` CLI.
+
+    MCP apps are often GUI apps that don't inherit your shell's PATH, so the
+    config gets a full path rather than a bare ``dataquery``.
+    """
+    script = Path(sys.executable).with_name("dataquery.exe" if os.name == "nt" else "dataquery")
+    if script.is_file():
+        return [str(script)]
+    # e.g. a --user install, whose scripts live apart from the interpreter
+    return [sys.executable, "-m", "dataquery.cli"]
+
+
+def server_entry(url: Optional[str] = None) -> Dict[str, Any]:
+    """The server entry: this environment's ``mcp-connect``, with no secrets in it."""
+    command, *args = dataquery_command()
+    args.append("mcp-connect")
+    if url:
+        args += ["--url", url]
+    return {"command": command, "args": args}
+
+
+def _app_data_dir() -> Path:
+    """The per-user application data directory for this OS."""
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support"
+    if sys.platform == "win32":
+        return Path(os.environ.get("APPDATA") or Path.home() / "AppData" / "Roaming")
+    return Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+
+
+@dataclass(frozen=True)
+class JsonApp:
+    """An MCP app that keeps its user-level servers in a JSON file."""
+
+    label: str
+    parts: Tuple[str, ...]  # the file, relative to the app-data or home directory
+    in_app_data: bool
+    servers_key: str = "mcpServers"
+    stdio_type: bool = False  # the app's schema names the transport: "type": "stdio"
+
+    def config_path(self) -> Path:
+        return (_app_data_dir() if self.in_app_data else Path.home()).joinpath(*self.parts)
+
+    def add(self, name: str, entry: Dict[str, Any]) -> Tuple[Path, bool]:
+        """Add or replace the server in this app's config; returns ``(path, replaced)``."""
+        if self.stdio_type:
+            entry = {"type": "stdio", **entry}
+        path = self.config_path()
+        return path, add_to_config_file(path, name, entry, self.servers_key)
+
+
+JSON_APPS: Dict[str, JsonApp] = {
+    "claude-desktop": JsonApp("Claude Desktop", ("Claude", "claude_desktop_config.json"), in_app_data=True),
+    "cursor": JsonApp("Cursor", (".cursor", "mcp.json"), in_app_data=False, stdio_type=True),
+    "vscode": JsonApp(
+        "VS Code", ("Code", "User", "mcp.json"), in_app_data=True, servers_key="servers", stdio_type=True
+    ),
+}
+
+
+def codex_config_path() -> Path:
+    """The Codex config, shared by the ChatGPT desktop app, the Codex CLI and its IDE extension."""
+    return Path.home() / ".codex" / "config.toml"
+
+
+def _write_atomically(path: Path, text: str) -> None:
+    """Replace ``path`` with ``text`` in one step, keeping the file's permissions."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")  # created 0600
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(text)
+        if path.exists():
+            # Keep the file's own permissions: it may hold other servers' secrets.
+            shutil.copymode(path, tmp)
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def add_to_config_file(path: Path, name: str, entry: Dict[str, Any], servers_key: str = "mcpServers") -> bool:
+    """Add or replace ``<servers_key>[name]`` in an MCP app's JSON config.
+
+    Everything else in the file is kept, and a file that isn't valid JSON is
+    left untouched. Returns ``True`` if an existing entry was replaced.
+    """
+    path = path.expanduser().resolve()  # through a symlink, so a dotfiles link survives
+    config: Any = {}
+    if path.exists():
+        text = path.read_text(encoding="utf-8")
+        if text.strip():
+            try:
+                config = json.loads(text)
+            except json.JSONDecodeError as exc:
+                raise ConfigurationError(f"{path} is not valid JSON ({exc}); fix it and re-run") from exc
+    servers = config.setdefault(servers_key, {}) if isinstance(config, dict) else None
+    if not isinstance(servers, dict):
+        raise ConfigurationError(f"{path} has no usable '{servers_key}' object; fix it and re-run")
+    replaced = name in servers
+    servers[name] = entry
+    _write_atomically(path, json.dumps(config, indent=2) + "\n")
+    return replaced
+
+
+def add_to_codex(name: str, entry: Dict[str, Any]) -> Tuple[Path, bool]:
+    """Add or replace the server in the Codex config; returns ``(path, replaced)``.
+
+    The table goes between marker comments, so a re-run replaces exactly what an
+    earlier run wrote and the rest of the file stays byte for byte. A server of
+    the same name added some other way is left alone, and nothing is written
+    unless the result parses back to this entry.
+    """
+    path = codex_config_path().resolve()
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    try:
+        servers = tomllib.loads(text).get("mcp_servers", {})
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigurationError(f"{path} is not valid TOML ({exc}); fix it and re-run") from exc
+
+    begin, end = f"# >>> dataquery mcp-install: {name} >>>", f"# <<< dataquery mcp-install: {name} <<<"
+    # A JSON string (non-ASCII left as is) is also a valid TOML basic string.
+    args = ", ".join(json.dumps(arg, ensure_ascii=False) for arg in entry["args"])
+    block = (
+        f"{begin}\n[mcp_servers.{name}]\ncommand = {json.dumps(entry['command'], ensure_ascii=False)}\n"
+        f"args = [{args}]\n{end}\n"
+    )
+    ours = re.compile(rf"^{re.escape(begin)}$.*?^{re.escape(end)}$\n?", re.MULTILINE | re.DOTALL)
+    replaced = ours.search(text) is not None
+    if replaced:
+        new_text = ours.sub(lambda _: block, text, count=1)
+    elif isinstance(servers, dict) and name in servers:
+        raise ConfigurationError(
+            f"{path} already has a '{name}' server that mcp-install didn't add; remove its "
+            f"[mcp_servers.{name}] table and re-run, or pick another --name"
+        )
+    else:
+        separator = "" if not text.strip() else ("\n" if text.endswith("\n") else "\n\n")
+        new_text = text + separator + block
+
+    try:
+        written = tomllib.loads(new_text).get("mcp_servers", {}).get(name)
+    except (tomllib.TOMLDecodeError, AttributeError):
+        written = None
+    if written != entry:
+        raise ConfigurationError(f"Couldn't add '{name}' to {path} cleanly; add this to it by hand:\n{block}")
+    _write_atomically(path, new_text)
+    return path, replaced
+
+
+def add_to_claude_code(name: str, entry: Dict[str, Any]) -> None:
+    """Register the server in Claude Code's user scope through its own CLI.
+
+    A user-scope server of the same name is replaced, so re-running updates it.
+    """
+    spec = json.dumps({"type": "stdio", **entry})
+    claude = shutil.which("claude")
+    if claude is None:
+        raise ConfigurationError(
+            f"Claude Code CLI ('claude') not found on PATH. Add the server yourself with:\n"
+            f"  claude mcp add-json -s user {name} '{spec}'"
+        )
+
+    def claude_mcp(*args: str) -> "subprocess.CompletedProcess[str]":
+        try:
+            return subprocess.run(
+                [claude, "mcp", *args], capture_output=True, text=True, timeout=_CLAUDE_CLI_TIMEOUT, check=False
+            )
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            raise ConfigurationError(f"'claude mcp {args[0]}' failed: {exc}") from exc
+
+    claude_mcp("remove", "-s", "user", name)  # fails harmlessly when there is none
+    result = claude_mcp("add-json", "-s", "user", name, spec)
+    if result.returncode != 0:
+        raise ConfigurationError(f"'claude mcp add-json' failed: {(result.stderr or result.stdout).strip()}")

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/dataquery/sse/client.py

@@ -12,7 +12,7 @@ import aiohttp
 
 from .. import constants as C
 from ..transport.auth import OAuthManager
-from ..types.models import ClientConfig
+from ..types.models import ClientConfig, merge_headers
 from .event_store import SSEEventIdStore
 
 logger = logging.getLogger(__name__)
@@ -157,10 +157,10 @@ class SSEClient:
     async def _get_headers(self) -> dict:
         headers = await self.auth_manager.get_headers()
         headers["Accept"] = "text/event-stream"
-        headers.update(self.config.get_custom_headers())
         if self._last_event_id is not None:
             headers["Last-Event-ID"] = self._last_event_id
-        return headers
+        # Custom headers go underneath, so they can never replace the stream's own headers.
+        return merge_headers(self.config.get_custom_headers(), headers)
 
     def _base_delay(self) -> float:
         """The reconnect floor: the server-supplied ``retry:`` hint, otherwise the configured ``reconnect_delay``."""

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/dataquery/transport/rate_limiter.py

@@ -117,8 +117,12 @@ class EnhancedTokenBucketRateLimiter:
 
         start_time = time.time()
 
-        async with self._get_lock():
-            while True:
+        while True:
+            # The lock guards only the bucket bookkeeping. It is deliberately released
+            # before sleeping: holding it across the await would let one waiting task
+            # monopolise the limiter, blocking every other acquire(), reset() and
+            # shutdown() for the whole wait even though no shared state is in use.
+            async with self._get_lock():
                 self._refill_tokens()
 
                 if self.state.tokens >= 1.0:
@@ -129,12 +133,12 @@ class EnhancedTokenBucketRateLimiter:
 
                 wait_time = self._calculate_wait_time()
 
-                if timeout is not None:
-                    elapsed = time.time() - start_time
-                    if elapsed + wait_time > timeout:
-                        return False
+            if timeout is not None:
+                elapsed = time.time() - start_time
+                if elapsed + wait_time > timeout:
+                    return False
 
-                await asyncio.sleep(min(wait_time, 0.1))
+            await asyncio.sleep(min(wait_time, C.RATE_LIMIT_POLL_INTERVAL_SECONDS))
 
     def _refill_tokens(self):
         """Refill tokens based on time elapsed."""

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/dataquery/types/models.py

@@ -2,15 +2,23 @@
 
 import asyncio
 import base64
+import re
 import time
 from datetime import date, datetime, timedelta, timezone
 from enum import Enum
 from pathlib import Path
-from typing import Any, Dict, List, Literal, Optional, Union, cast
+from typing import Any, Dict, List, Literal, Mapping, Optional, Tuple, Union, cast
 
 from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator
 
 from .. import constants as C
+from .exceptions import ConfigurationError
+
+# RFC 9110 field-name token.
+_HEADER_NAME_RE = re.compile(r"[!#$%&'*+\-.^_`|~0-9A-Za-z]+")
+
+# Sent by the SDK on every request, so a custom value would never reach the server.
+_SDK_OWNED_HEADERS = frozenset({"authorization"})
 
 
 def _reveal_secret(value: Union[str, SecretStr, None]) -> Optional[str]:
@@ -22,6 +30,19 @@ def _reveal_secret(value: Union[str, SecretStr, None]) -> Optional[str]:
     return value
 
 
+def merge_headers(*layers: Mapping[str, str]) -> Dict[str, str]:
+    """Merge header mappings left to right, later layers winning.
+
+    Names compare case-insensitively, as in HTTP, so ``user-agent`` replaces
+    ``User-Agent`` instead of both going on the wire.
+    """
+    merged: Dict[str, Tuple[str, str]] = {}
+    for layer in layers:
+        for name, value in layer.items():
+            merged[name.lower()] = (name, value)
+    return dict(merged.values())
+
+
 class DownloadStatus(str, Enum):
     """Status of a download operation."""
 
@@ -51,9 +72,10 @@ class ClientConfig(BaseModel):
     )
     context_path: Optional[str] = Field(default="/research/dataquery-authe/api/v2", description="API context path")
     api_version: str = Field(default="2.0.0", description="API version")
-    x_user_agent: Optional[str] = Field(
-        default=None,
-        description="Optional value for the X-User-Agent header sent on each API request",
+    custom_headers: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Extra headers sent on every API request (e.g. X-User-Agent); "
+        "set per client, never read from the environment",
     )
     files_base_url: Optional[str] = Field(
         default="https://api-dataquery.jpmchase.com",
@@ -251,11 +273,28 @@ class ClientConfig(BaseModel):
         return kwargs
 
     def get_custom_headers(self) -> Dict[str, str]:
-        """Return extra headers to attach to every API request (e.g. X-User-Agent)."""
-        headers: Dict[str, str] = {}
-        if self.x_user_agent:
-            headers["X-User-Agent"] = self.x_user_agent
-        return headers
+        """Return a validated copy of ``custom_headers``, the extra headers sent on every API request.
+
+        Raises :class:`ConfigurationError` for a header that cannot be sent as given. The message
+        names the header but never echoes its value, which may be a secret.
+        """
+        seen: set[str] = set()
+        for name, value in self.custom_headers.items():
+            if not isinstance(name, str) or not _HEADER_NAME_RE.fullmatch(name):
+                raise ConfigurationError(f"Invalid HTTP header name: {name!r}")
+            if not isinstance(value, str) or any(ch in value for ch in "\r\n\0"):
+                raise ConfigurationError(f"Header {name!r} must have a string value without CR, LF or NUL characters")
+            key = name.lower()
+            if key in _SDK_OWNED_HEADERS:
+                raise ConfigurationError(
+                    f"Header {name!r} is set by the SDK; configure client_id/client_secret or bearer_token instead"
+                )
+            if key in seen:
+                raise ConfigurationError(
+                    f"Header {name!r} appears more than once in custom_headers (names are case-insensitive)"
+                )
+            seen.add(key)
+        return dict(self.custom_headers)
 
     @property
     def api_base_url(self) -> str:

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/dataquery/utils.py

@@ -175,9 +175,6 @@ DATAQUERY_DEFAULT_DIR=files
 # Default: DATAQUERY-SDK/1.2.1
 DATAQUERY_USER_AGENT=DATAQUERY-SDK/1.2.1
 
-# Optional custom X-User-Agent header sent on every API request
-# DATAQUERY_X_USER_AGENT=MyApp/1.0
-
 # Enable HTTP/2 support (true/false)
 # Default: true
 DATAQUERY_ENABLE_HTTP2=true

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/dataquery_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataquery-sdk
-Version: 1.2.5
+Version: 1.2.7
 Summary: Python SDK for DATAQUERY Data API - Query, download, and check availability of economic data files
 Author-email: DATAQUERY SDK Team <dataquery_support@jpmorgan.com>
 Project-URL: Homepage, https://github.com/jpmorganchase/dataquery-sdk
@@ -50,7 +50,7 @@ Requires-Dist: pymdown-extensions>=11.0.0; extra == "docs"
 Provides-Extra: pandas
 Requires-Dist: pandas>=2.0.0; extra == "pandas"
 Provides-Extra: mcp
-Requires-Dist: fastmcp>=2.14; extra == "mcp"
+Requires-Dist: fastmcp<4,>=2.14; extra == "mcp"
 Provides-Extra: all
 Requires-Dist: pytest>=7.0.0; extra == "all"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "all"
@@ -63,7 +63,7 @@ Requires-Dist: mkdocs-material>=9.0.0; extra == "all"
 Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "all"
 Requires-Dist: mike>=1.1.0; extra == "all"
 Requires-Dist: pandas>=2.0.0; extra == "all"
-Requires-Dist: fastmcp>=2.14; extra == "all"
+Requires-Dist: fastmcp<4,>=2.14; extra == "all"
 Requires-Dist: pip-audit>=2.7.0; extra == "all"
 Requires-Dist: build>=1.3.0; extra == "all"
 Requires-Dist: urllib3>=2.7.0; extra == "all"
@@ -467,8 +467,39 @@ pip install "dataquery-sdk[mcp]"
 
 ### Wire it into an MCP client
 
-Add the server to your client's MCP config (`claude_desktop_config.json`,
-`.mcp.json`, or the equivalent for your host):
+**One-time setup (recommended).** Install, then run `mcp-install` once:
+
+```bash
+pip install "dataquery-sdk[mcp]"
+dataquery mcp-install                  # Claude Desktop (the default)
+dataquery mcp-install --app <app>      # one of the apps below
+dataquery mcp-install --config-file ~/.some-app/mcp.json   # any other app with an mcpServers JSON file
+```
+
+| `--app` | Where the server goes |
+|---|---|
+| `claude-desktop` | Claude Desktop's `claude_desktop_config.json` |
+| `claude-code` | Claude Code, user scope (via `claude mcp add-json`) |
+| `chatgpt` | `~/.codex/config.toml`, which the ChatGPT desktop app shares with the Codex CLI and IDE extension; ChatGPT on the web can't run local servers |
+| `cursor` | `~/.cursor/mcp.json` |
+| `vscode` | VS Code's user-profile `mcp.json` (default profile) |
+
+It prompts for your client ID and secret (the secret without echo) and saves
+them to `~/.dataquery/.env`, owner-only (see [Credentials](#credentials)). It
+then adds a `dataquery` server to the app's user config. The entry runs this
+environment's `dataquery mcp-connect` by absolute path, because GUI apps don't
+see your shell's `PATH`, and it contains no secrets. Other servers and settings
+in the file are kept. Restart the app to load it.
+
+- Re-run it any time to update the credentials or the entry.
+- `--client-id`/`--client-secret` or `--bearer-token` skip the prompt, but flags
+  are visible in the process list.
+- `--url` and `--name` register another environment alongside the first.
+- Run it from an environment you keep (pip or pipx), not a throwaway `uvx` one,
+  because the entry points at that environment's executable.
+
+**Manual setup.** Or add the server to your client's MCP config yourself
+(`claude_desktop_config.json`, `.mcp.json`, or the equivalent for your host):
 
 ```json
 {
@@ -639,6 +670,43 @@ async with DataQuery(client_id="...", client_secret="...", timeout=60.0) as dq:
     ...
 ```
 
+### Custom request headers
+
+Headers are configured per client, on `ClientConfig` or as `DataQuery(...)`
+kwargs, and are never read from the environment, so several clients in one
+process can identify themselves differently. They are sent on every DataQuery
+API request (JSON, file and SSE), but not on the OAuth token request.
+
+```python
+config = ClientConfig(
+    client_id="...",
+    client_secret="...",
+    custom_headers={
+        "X-User-Agent": "RiskEngine/2.1",
+        "X-Team": "rates",
+        "X-Request-Source": "nightly-batch",
+    },
+)
+
+async with DataQuery(config) as dq:
+    ...
+
+# Or as kwargs:
+async with DataQuery(custom_headers={"X-User-Agent": "RiskEngine/2.1"}) as dq:
+    ...
+```
+
+- A custom header replaces an SDK default of the same name (e.g. `User-Agent`),
+  but never `Authorization`, which comes from `client_id`/`client_secret` or
+  `bearer_token`, and never the SSE stream's `Accept` / `Last-Event-ID`.
+- Invalid headers (a bad name, CR/LF in a value, a name repeated in another
+  case, `Authorization`) raise `ConfigurationError` before the first request.
+  The error names the header but never shows its value.
+- Kwarg overrides are written onto the `ClientConfig` you pass in, so give each
+  client its own config instead of sharing one.
+- The `x_user_agent` option and `DATAQUERY_X_USER_AGENT` are gone; send
+  `X-User-Agent` through `custom_headers` like any other header.
+
 ## Logging
 
 The SDK logs through [structlog](https://www.structlog.org/) and emits

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/dataquery_sdk.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ dataquery/cli.py
 dataquery/dataquery.py
 dataquery/export.py
 dataquery/function_registry.py
+dataquery/mcp_install.py
 dataquery/mcp_proxy.py
 dataquery/py.typed
 dataquery/utils.py

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/dataquery_sdk.egg-info/requires.txt

@@ -16,7 +16,7 @@ mkdocs-material>=9.0.0
 mkdocstrings[python]>=0.24.0
 mike>=1.1.0
 pandas>=2.0.0
-fastmcp>=2.14
+fastmcp<4,>=2.14
 pip-audit>=2.7.0
 build>=1.3.0
 urllib3>=2.7.0
@@ -42,7 +42,7 @@ mike>=1.1.0
 pymdown-extensions>=11.0.0
 
 [mcp]
-fastmcp>=2.14
+fastmcp<4,>=2.14
 
 [pandas]
 pandas>=2.0.0

{dataquery_sdk-1.2.5 → dataquery_sdk-1.2.7}/pyproject.toml

@@ -77,7 +77,7 @@ pandas = [
     "pandas>=2.0.0",
 ]
 mcp = [
-    "fastmcp>=2.14",
+    "fastmcp>=2.14,<4",
 ]
 all = [
     "pytest>=7.0.0",
@@ -91,7 +91,7 @@ all = [
     "mkdocstrings[python]>=0.24.0",
     "mike>=1.1.0",
     "pandas>=2.0.0",
-    "fastmcp>=2.14",
+    "fastmcp>=2.14,<4",
     "pip-audit>=2.7.0",
     "build>=1.3.0",
     "urllib3>=2.7.0",

dataquery_sdk-1.2.5/dataquery/constants/rate_limit.py

@@ -1,5 +0,0 @@
-"""Rate-limiter tunables."""
-
-from __future__ import annotations
-
-RATE_LIMIT_MIN_WAIT_SECONDS = 0.2