Stock Trends Market Intelligence

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. 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; 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). 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, then Connect a local stdio MCP client. Read Paid Mode Configuration and the Security Model 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:

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 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 below and the Cross-Platform Package Install / Stdio Validation Report.

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:

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

For a reproducible install pinned to an exact release, append @ (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 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 and the MCP Registry Readiness Implementation Notes). 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. 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 addition to the public npm install above, this repository's package can also be built and packed locally as an installable npm artifact — on Windows and WSL2 Ubuntu (see the Cross-Platform Package Install / Stdio Validation Report). This path is useful for testing an unreleased local build against the published package's identity; it is not required for normal installation.

• The artifact is not retained in this repository — no .tgz is committed, and none ships with a checkout.
• package.json carries the same public identity the published npm package uses: the scoped name @stocktrends-publications/stocktrends-mcp-server, the MCP Registry identity mcpName com.stocktrends/market-intelligence, and an explicit public publishConfig (access: public, the public npm registry) — see the Package Publication Configuration Implementation Notes and the MCP Registry Readiness Implementation Notes.
• To use this path, build the artifact yourself from a reviewed checkout.

To build the local artifact yourself from a checkout:

git clone <repository-url>

cd stocktrends-mcp-server npm install npm run build npm pack

This produces stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz in the current directory — the reviewed closed artifact allowlist is dist/**/*.js, dist/**/*.d.ts, README.md, and LICENSE (see the Package Metadata and Closed Artifact Allowlist Implementation). Install it into a separate consumer project (not this checkout):

npm install <path-to-local-stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz>

This local-artifact path and the Public npm Installation path above install the same reviewed package identity through two different c