Stock Trends MCP Server

Local Model Context Protocol (MCP) adapter for public Stock Trends API resources.

Architecture Boundary (What This Server Is)

This repository is a thin local stdio adapter over the front-facing Stock Trends API. It has no independent analytical authority of its own.

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? Start with the Default / Free Mode Quickstart below to install and run the server credential-free, then Connect a local stdio MCP client to wire it into an MCP client, and 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 exactly one MCP tool: stocktrends_estimate_workflow_cost.
• 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 @<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 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). Version 1.0.1 prepares this package's official MCP Registry identity (com.stocktrends/market-intelligence, declared in server.json); MCP Registry publication itself is a separate, later, explicitly authorized step and is not claimed as complete by this README.

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 channels; prefer the public npm install unless you specifically need to test an unreleased local build.

Once installed, the package provides an npm-managed command shim rather than a checkout-relative dist/server.js path. On POSIX systems (Linux, macOS, WSL) this is a symlink at node_modules/.bin/stocktrends-mcp-server; on Windows it is a generated shim at node_modules\.bin\stocktrends-mcp-server.cmd. Do not assume the bin is installed globally — resolve it from the consumer project's own node_modules/.bin. See Connect a local stdio MCP client below for package-installed client configuration examples alongside the checkout examples.

Inspect with MCP Inspector (no API key)

After building (npm run build), point the MCP Inspector at the compiled stdio server, with no paid-mode environment variables set:

npx @modelcontextprotocol/inspector node dist/server.js

In the Inspector UI, confirm:

• The tool list contains exactly stocktrends_estimate_workflow_cost, and the paid 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) are not visible.
• The prompts list is empty, if the client exposes a prompts panel.
• Public resources (for example stocktrends://api/openapi, stocktrends://ai/context) are listed and readable without any credential configured.

This check confirms the free/default boundary without requiring or triggering any paid execution.

For a fuller step-by-step Inspector procedure — default/free listing, paid-exposed listing without execution, and a rollback checklist — see the Phase 5A MCP Inspector Validation Runbook (its paid-exposed surface and resource counts were correct when written for the Phase 4-era three-tool surface; current counts are documented in this README).

Secret Safety (free mode)

Free/default mode needs no API key, so nothing secret is involved in this quickstart. Always test and demonstrate default mode without a key. The full credential-handling rules — placeholders only, never commit or paste a real key — are consolidated in the top-level Secret Safety section.

Connect a local stdio MCP client