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