npm package: @strata-js/mcp
Description: MCP server for Strata.js service discovery and documentation.
Author: Christopher S. Case
Latest version: 0.3.0

# @strata-js/mcp

An MCP (Model Context Protocol) server for [Strata.js](https://gitlab.com/strata-js). It connects to your Strata
backend and exposes service discovery, documentation, and request capabilities to AI tools like Claude Code, Cursor,
Windsurf, and anything else that speaks MCP.

## Quick Start

No installation required. Add the server to your AI tool's MCP configuration and point it at your Redis backend.

### Claude Code

Add to `.mcp.json` in your project root (or `~/.claude/mcp.json` globally):

```json
{
  "mcpServers": {
    "strata": {
      "command": "npx",
      "args": ["-y", "@strata-js/mcp"],
      "env": {
        "STRATA_REDIS_HOST": "localhost",
        "STRATA_REDIS_PORT": "6379"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "strata": {
      "command": "npx",
      "args": ["-y", "@strata-js/mcp"],
      "env": {
        "STRATA_REDIS_HOST": "localhost",
        "STRATA_REDIS_PORT": "6379"
      }
    }
  }
}
```

### Global Install

```bash
npm install -g @strata-js/mcp
strata-mcp
```

## Tools

The server exposes three MCP tools:

| Tool | Description |
|------|-------------|
| `strata-discover` | List all available services, their contexts, and operations |
| `strata-service-info` | Get detailed info about a specific service group |
| `strata-request` | Send a request to a Strata service and receive a response |

### strata-discover

Takes no arguments. Returns all services registered on the message bus.

### strata-service-info

| Parameter | Type | Description |
|-----------|------|-------------|
| `serviceGroup` | `string` | The service group to inspect (e.g., `"RecordService"`) |

### strata-request

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `serviceGroup` | `string` | Yes | The service group to call (e.g., `"OrderService"`) |
| `context` | `string` | Yes | The context within the service (e.g., `"orders"`) |
| `operation` | `string` | Yes | The operation to perform (e.g., `"list"`) |
| `payload` | `object` | Yes | The request payload as a JSON object |
| `auth` | `string` | No | Authentication token |
| `timeout` | `number` | No | Timeout in milliseconds |

## Resources

The server provides Strata.js documentation as MCP resources, available for AI tools to read on demand:

| URI | Description |
|-----|-------------|
| `strata://docs/overview` | Framework overview, core concepts, architecture, and message flow |
| `strata://docs/writing-services` | Guide to writing Strata services -- contexts, operations, middleware |
| `strata://docs/client-usage` | Using Strata clients -- making requests, discovery, error handling |
| `strata://docs/project-structure` | Recommended project structure following the iDesign pattern |
| `strata://docs/testing` | Testing strategies for Strata services |

## Prompts

Four built-in prompts are available for guided workflows:

| Prompt | Description |
|--------|-------------|
| `explore-services` | Discover and explore all available services in the environment |
| `test-service` | Test a specific service with example requests |
| `learn-strata` | Learn Strata.js concepts from the built-in documentation |
| `create-context` | Scaffold a new Strata context with operations and types |

## Read-Only Mode

By default, the server blocks operations that could modify data. The following patterns are blocked:

- `save*` -- all save operations
- `delete*` -- all delete operations
- `remove*` -- all remove operations
- `purge*` -- all purge operations

This means an AI agent can safely explore and query your services without accidentally mutating state.

To disable read-only mode and allow all operations:

```json
{
  "mcpServers": {
    "strata": {
      "command": "npx",
      "args": ["-y", "@strata-js/mcp"],
      "env": {
        "STRATA_BLOCK_RULES": ""
      }
    }
  }
}
```

### Custom Block Rules

Block rules use the format `serviceGroup:context:operation` with `*` as a wildcard. Multiple rules are
comma-separated.

```bash
# Block all operations on a specific service
STRATA_BLOCK_RULES="RecordService:*:*"

# Block a specific context across all services
STRATA_BLOCK_RULES="*:policy:*"

# Combine multiple rules
STRATA_BLOCK_RULES="*:*:save*,*:*:delete*,RecordService:policy:*"
```

## Configuration

All configuration is done through environment variables.

| Variable | Description | Default |
|----------|-------------|---------|
| `STRATA_BACKEND_TYPE` | Backend type (`redis` or `redis-streams`) | `redis` |
| `STRATA_REDIS_HOST` | Redis host | `localhost` |
| `STRATA_REDIS_PORT` | Redis port | `6379` |
| `STRATA_REDIS_DB` | Redis database number | `0` |
| `STRATA_REDIS_USERNAME` | Redis username | -- |
| `STRATA_REDIS_PASSWORD` | Redis password | -- |
| `STRATA_CLIENT_NAME` | Client identifier on the message bus | `strata-mcp` |
| `STRATA_BLOCK_RULES` | Comma-separated block rules (see above) | `*:*:save*,*:*:delete*,*:*:remove*,*:*:purge*` |

The server also supports `.env` files via [dotenv](https://github.com/motdotla/dotenv).

### Production Example

```json
{
  "mcpServers": {
    "strata": {
      "command": "npx",
      "args": ["-y", "@strata-js/mcp"],
      "env": {
        "STRATA_REDIS_HOST": "redis.internal.example.com",
        "STRATA_REDIS_PORT": "6380",
        "STRATA_REDIS_DB": "2",
        "STRATA_REDIS_USERNAME": "mcp-readonly",
        "STRATA_REDIS_PASSWORD": "hunter2",
        "STRATA_CLIENT_NAME": "mcp-prod"
      }
    }
  }
}
```

## Requirements

- Node.js >= 22.0.0
- A running Redis instance with Strata services connected

## License

MIT