Sentinel-MCP

Sentinel-MCP is an extensible trading-intelligence platform whose first interface is a Model Context Protocol (MCP) server. Milestone 1 provides a robust server foundation: configuration, structured logging, automatic tool registration, error boundaries, testing, and a diagnostic tool.

Trading execution and market-data integrations are intentionally out of scope for this milestone.

Architecture

The application follows dependency-oriented boundaries:

• core creates the MCP server and cross-cutting concerns such as logging and errors.
• config validates the runtime environment before startup.
• tools contains independently registerable MCP capabilities.
• services contains application logic that tools depend on.
• models contains stable, provider-agnostic data contracts.

Future provider adapters (TradingView, Dhan, NSE, news, and caching) can be added behind service interfaces without changing the MCP entry point.

Requirements

• Node.js 22 or later (current LTS recommended)
• pnpm 9 or later

Installation

git clone <your-repository-url>
cd sentinel-mcp
pnpm install
cp .env.example .env

Development

pnpm dev

Build and run

pnpm build
pnpm start

The server communicates over standard input/output, as required by local MCP clients. Logs are written to stderr so they never corrupt the MCP protocol stream.

To use it with Claude Desktop after building, add a server entry that invokes the built file:

{
  "mcpServers": {
    "sentinel-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/sentinel-mcp/dist/index.js"]
    }
  }
}

Available tools

get_server_info

Returns structured runtime data including server name, version, status, ISO timestamp, uptime, Node.js version, and host platform. It is a safe connection and health diagnostic.

Quality commands

pnpm typecheck
pnpm lint
pnpm test
pnpm format:check

Folder structure

src/
  config/       Environment validation and runtime settings
  core/         Server composition, errors, logging
  models/       Provider-agnostic application contracts
  providers/    External-provider contracts and future adapters
  schemas/      Shared validation schemas
  services/     Reusable application services
  tools/        Self-registering MCP tools and registry
  cache/        Cache implementations and policies
  types/        Shared TypeScript declarations
  utils/        Small, framework-independent helpers
tests/          Vitest coverage for foundation components
docs/           Project documentation (reserved for design documents)
scripts/        Project automation (reserved for operational scripts)

Configuration

Copy .env.example to .env. The defaults work for local development.

Variable	Default	Purpose
SENTINEL_APP_NAME	Sentinel-MCP	Server identity exposed to clients
SENTINEL_APP_VERSION	0.1.0-alpha	Server version exposed to clients
SENTINEL_LOG_LEVEL	info	Pino log level
SENTINEL_TRANSPORT	stdio	MCP transport for this milestone

Roadmap

1. Provider interfaces and resilient market-data adapters.
2. Shared cache, rate-limit, and retry policies.
3. Symbol lookup and market intelligence tools.
4. News enrichment and configurable alerting.
5. Optional authenticated provider integrations.

License

Choose and add an open-source license before public distribution.