Skip to main content
Glama
Commish MCP

Commish MCP

by alexmillsnl
README.md
# Commish MCP

An MCP (Model Context Protocol) server for **fantasy sports league commissioners** — giving AI assistants league-wide context and commissioner-oriented tools.

Commish MCP is not a thin wrapper around a single fantasy API. The domain is **fantasy commissioner operations**: league overviews, standings, matchup results, manager activity, transactions, recaps, and storylines. Provider-specific APIs (Yahoo first) sit underneath a provider abstraction.

## Current state

🚧 **Early development — initial scaffolding.**

- MCP server boots over stdio and registers one example tool (`get_league_overview`)
- Provider-agnostic architecture with a Yahoo skeleton in place
- **No live fantasy data yet** — the Yahoo OAuth2 client and API integration are not implemented

## Planned providers

| Provider      | Status                                         |
| ------------- | ---------------------------------------------- |
| Yahoo Fantasy | First — skeleton in place, integration pending |
| Sleeper       | Future                                         |
| ESPN          | Potential future                               |

## Planned capabilities

Commissioner-focused tools on the roadmap (none implemented yet):

- Weekly recaps and league storylines
- League health and manager activity
- Lineup auditing
- Transaction reports
- Playoff context and standings deep-dives

## Architecture

```text
Yahoo API
   ↓
YahooProvider            (src/providers/yahoo)
   ↓
Normalized domain models (src/domain)
   ↓
Commissioner services    (src/services)
   ↓
MCP tools                (src/tools)
   ↓
AI client
```

Key principles:

- **Provider independence** — tools operate on normalized domain models (`src/domain`), never raw provider payloads. Raw Yahoo types live in `src/providers/yahoo/types.ts` and must not leak upward.
- **Commissioner-first** — services (`src/services`) combine provider data into league-level views; tool handlers stay thin.
- **Strong typing** — provider payloads and domain objects are separate types; no `any`.

## Getting started

Requires Node.js 22+ (`.nvmrc` provided).

```bash
npm install
npm run build
npm test
npm run typecheck
```

### Scripts

| Command             | Purpose                        |
| ------------------- | ------------------------------ |
| `npm run build`     | Compile `src/` → `dist/`       |
| `npm run dev`       | Run with watch mode via tsx    |
| `npm start`         | Run the compiled server        |
| `npm test`          | Run unit tests (vitest)        |
| `npm run typecheck` | Type-check `src/` and `tests/` |
| `npm run lint`      | ESLint                         |
| `npm run format`    | Prettier                       |

### Adding to an MCP client

Example Claude Desktop configuration:

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

## Configuration

Copy `.env.example` to `.env` (never committed) and fill in Yahoo credentials from an app registered at [developer.yahoo.com/apps](https://developer.yahoo.com/apps/):

```text
YAHOO_CLIENT_ID=
YAHOO_CLIENT_SECRET=
YAHOO_REDIRECT_URI=http://localhost:8787/callback
```

All variables are optional today: without them the server runs and tools explain what is missing. OAuth2 support (authorization-code flow, token refresh, secure local token storage) is the next milestone.

## Project structure

```text
src/
ā”œā”€ā”€ index.ts              # stdio entrypoint
ā”œā”€ā”€ server/server.ts      # server assembly + tool registration
ā”œā”€ā”€ tools/                # MCP tools (thin handlers)
│   ā”œā”€ā”€ league/
│   └── types.ts          # ToolModule / ToolContext pattern
ā”œā”€ā”€ services/             # commissioner services (combine provider data)
ā”œā”€ā”€ providers/
│   ā”œā”€ā”€ provider.ts       # FantasyProvider interface
│   └── yahoo/            # client, provider, raw payload types
ā”œā”€ā”€ domain/               # normalized league/team/matchup/transaction models
ā”œā”€ā”€ config/env.ts         # zod-validated environment
└── utils/
tests/                   # vitest unit + in-memory MCP integration tests
```

## License

[MIT](./LICENSE)

TDQS

A3.5/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool available, there is no potential for confusion between tools. The purpose of get_league_overview is clear and unambiguous.

Naming Consistency5/5

The single tool follows a clean verb_noun pattern, which is consistent with well-named MCP tools. There are no conflicting conventions.

Tool Count2/5

A single tool is far too few for a server whose name implies commissioner functionality. While the tool itself is useful, one tool cannot reasonably cover the expected scope.

Completeness1/5

The server only provides a read-only league overview. Critical commissioner actions such as roster management, trade processing, waiver claims, or settings updates are entirely missing, leaving the surface severely incomplete.

Maintenance

ActivityStale
ResponsivenessNo recent community issues