# 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

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

## Development

```bash
pnpm dev
```

## Build and run

```bash
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:

```json
{
  "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

```bash
pnpm typecheck
pnpm lint
pnpm test
pnpm format:check
```

## Folder structure

```text
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.