stocktrends-mcp-server

# Stock Trends MCP Server

Stock Trends Model Context Protocol (MCP) server for the live public Remote MCP and separately available local stdio clients.

## Architecture Boundary (What This Server Is)

This repository is a thin MCP adapter over the front-facing Stock Trends API. It powers the live public Remote MCP and supports local stdio; it has no independent analytical authority of its own.

## Public Remote MCP

Connect a remote MCP client to the Streamable HTTP endpoint:

```
https://mcp.stocktrends.com/mcp
```

Developer connection guidance is available at [developer.stocktrends.com/mcp](https://developer.stocktrends.com/mcp). The deployed remote surface exposes exactly 19 tools, ten public resources, and zero prompts. Connection and discovery require no Stock Trends subscription API key. Three tools are free: `stocktrends_estimate_workflow_cost`, `stocktrends_lookup_instruments`, and `stocktrends_resolve_instrument`. Sixteen tools are x402 V2 paid tools: the 12 GET tools `stocktrends_get_stim_latest`, `stocktrends_get_stim_history`, `stocktrends_get_indicators_latest`, `stocktrends_get_indicators_history`, `stocktrends_get_selections_latest`, `stocktrends_get_market_regime_latest`, `stocktrends_get_market_regime_history`, `stocktrends_get_breadth_sector_latest`, `stocktrends_get_leadership_summary_latest`, `stocktrends_get_screener_top`, `stocktrends_get_market_epoch_latest`, and `stocktrends_get_market_epoch_history`; and the four POST tools `stocktrends_evaluate_symbol` (`POST /v1/decision/evaluate-symbol`), `stocktrends_construct_portfolio` (`POST /v1/portfolio/construct`), `stocktrends_evaluate_portfolio` (`POST /v1/portfolio/evaluate`), and `stocktrends_compare_portfolios` (`POST /v1/portfolio/compare`). `stocktrends_get_selections_latest` returns the base selection universe, not the separately thresholded published ST-IM Select list.

For the paid remote tools, a payment-capable MCP client obtains and authorizes payment. It supplies that authorization in MCP request metadata as `x402/payment`; the adapter forwards it to the Stock Trends API in the upstream `PAYMENT-SIGNATURE` header and returns confirmed settlement metadata as `x402/payment-response`. These MCP metadata fields are distinct from the API headers. The server does not control a buyer wallet, hold private keys, sign payment authorizations, initiate spending, recompute Stock Trends intelligence, or execute securities trades. A client does not gain payment capability merely by connecting, and a conforming x402 REST buyer does not automatically implement this MCP-specific exchange. Do not automatically retry an uncertain payment outcome; for a POST tool, a settled payment can accompany an analytical HTTP error, and pending challenge state is bound to the adapter's canonical request body rather than independently cryptographically signing that body.

## Local stdio and Streamable HTTP configuration

Node.js **20+** is required for local use. Local stdio remains the default transport for local process startup and is fully supported. Source also supports explicit `STOCKTRENDS_MCP_TRANSPORT=streamable-http`, serving MCP at `/mcp` and operational checks at `/healthz` and `/readyz`; its local listener binds to `127.0.0.1:3000` by default. The deployed public endpoint above is distinct from this local configuration. Official MCP Registry version `1.0.2` is [published, active, and latest](https://registry.modelcontextprotocol.io/?q=com.stocktrends%2Fmarket-intelligence); it advertises both the local stdio npm package and the Remote MCP endpoint `https://mcp.stocktrends.com/mcp` over Streamable HTTP.

By default, a locally started `streamable-http` configuration is credential-free: ten public resources, the three free tools listed above, and no prompts. It refuses a configured API key, paid-tools/execution settings, or the separate local x402 relay/challenge/live/proof-forwarding settings. `STOCKTRENDS_ENABLE_REMOTE_X402_STIM=true` is the distinct, Streamable HTTP-only activation for the production-style Remote x402 registrations: it exposes the three free tools plus 16 x402-paid tools (19 total), without enabling API-key paid mode or the local challenge relay. This source-level activation is distinct from the deployed public service and is not a deployment guide. Local stdio retains separately gated subscription/API-key paid REST calls. Its optional, default-off x402 mode is challenge metadata inspection/relay only: it neither makes a payment nor forwards payment proof or payment headers, returns paid API data, or spends. MPP is not implemented.

Authority flows in one direction only:

```
Stock Trends dataset
  -> Stock Trends API
  -> published Stock Trends API responses/artifacts
  -> MCP adapter (this repository)
  -> external MCP clients/agents
```

The MCP adapter:

- Does not recompute Stock Trends data, ST-IM, or indicators.
- Does not access the Stock Trends database or control plane directly.
- Does not generate investment advice, research, or trading guidance.
- Only translates reviewed, published Stock Trends API responses into MCP resource and tool responses.

Public resources and the default/free mode described below are credential-free: no API key, subscription, or payment credential is required to install, inspect, or use them. The conditional paid ST-IM execution path is a separate, explicitly gated surface that is disabled by default (see [Conditional Paid ST-IM Tools](#conditional-paid-st-im-tools-subscriptionapi-key-execution)). An additional default-off x402 posture can expose the same paid semantic tool names. Relay plus challenge flags preserve the local mock-only behavior; a distinct third live flag may enable a capped, one-request no-key challenge path. Neither x402 mode accepts or forwards proof, sends a payment header, returns paid data, pays, or spends.

**New here?** For the public Remote MCP, use the endpoint and Developer Portal above. To run a local server, start with the [Default / Free Mode Quickstart](#default--free-mode-quickstart), then [Connect a local stdio MCP client](#connect-a-local-stdio-mcp-client). Read [Paid Mode Configuration](#paid-mode-configuration) and the [Security Model](docs/SECURITY_MODEL.md) before setting any paid variable.

## Default / Free Mode Quickstart

This is the recommended first path for installing or inspecting the server. In default mode, the server:

- Requires no API key.
- Performs no paid execution and creates no spend.
- Exposes three free MCP tools: `stocktrends_estimate_workflow_cost`, `stocktrends_lookup_instruments`, and `stocktrends_resolve_instrument`.
- Makes all public resources available credential-free.
- Registers zero MCP prompts.

### Setup

Using only the existing project scripts:

```sh
git clone <repository-url>
cd stocktrends-mcp-server
npm install
npm run build
```

This `git clone` + `npm install` + `npm run build` sequence, followed by local stdio execution of the compiled `dist/server.js`, remains fully supported and is the primary install channel for this repository. This package is also **publicly available from the npm registry** as `@stocktrends-publications/stocktrends-mcp-server` — see [Public npm Installation](#public-npm-installation) directly below. A third, distinct install path — a locally built npm package artifact (a local `.tgz`, not a registry install) — has also been validated cross-platform; see [Local Package Artifact Installation](#local-package-artifact-installation-build-it-yourself-alternative) below and the [Cross-Platform Package Install / Stdio Validation Report](docs/CROSS_PLATFORM_PACKAGE_INSTALL_STDIO_VALIDATION_REPORT.md).

No environment variables or `.env` file are required for this path. Do not set `STOCKTRENDS_ENABLE_PAID_TOOLS`, `STOCKTRENDS_API_KEY`, or `STOCKTRENDS_ENABLE_PAID_EXECUTION` while testing default/free mode.

Optional: `npm start` starts the local stdio server process directly and is mainly useful as a manual smoke check (it will sit waiting for JSON-RPC input on stdin). Stop it with Ctrl+C before launching the server via MCP Inspector below.

### Public npm Installation

This package is publicly published to the npm registry as `@stocktrends-publications/stocktrends-mcp-server`. Anyone can install it by name, credential-free, without cloning this repository:

```sh
npm install @stocktrends-publications/stocktrends-mcp-server
```

For a reproducible install pinned to an exact release, append `@<version>` (for example `@1.0.0`) to the command above; omit the version to receive the latest published release. Once installed, the package provides an npm-managed command shim (not a checkout-relative `dist/server.js` path) — see [Connect a local stdio MCP client](#connect-a-local-stdio-mcp-client) below for configuration examples covering both a package-installed shim and a checkout-relative path.

The `1.0.0` release was verified byte-for-byte (SHA-256) against its frozen, offline-validated release-candidate artifact before publication, and anonymous installation by name plus a Windows MCP `initialize`/list-only handshake were validated against the published package (see [`docs/SECURITY_MODEL.md` §18](docs/SECURITY_MODEL.md) and the [MCP Registry Readiness Implementation Notes](docs/MCP_REGISTRY_READINESS_IMPLEMENTATION_NOTES.md)). The published npm `1.0.1` artifact is likewise a historical one-free-tool release; that published-package result does not describe the current source checkout's three-tool free surface. Official MCP Registry version `1.0.2` for `com.stocktrends/market-intelligence` is [published, active, and latest](https://registry.modelcontextprotocol.io/?q=com.stocktrends%2Fmarket-intelligence). It advertises the existing npm `1.0.1` local stdio package and the Remote MCP endpoint `https://mcp.stocktrends.com/mcp` over Streamable HTTP; the Registry metadata version and npm package version are intentionally distinct.

### Local Package Artifact Installation (build-it-yourself alternative)

In addi