@withinfocus/tba-mcp-server 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +70 -502
  2. package/dist/index.js +1 -1
  3. package/package.json +5 -5
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # The Blue Alliance MCP Server
2
2
 
3
- A Model Context Protocol (MCP) server that provides access to The Blue Alliance API for FIRST Robotics Competition data. This server enables AI assistants and other MCP clients to retrieve comprehensive FRC team, event, and match information.
3
+ A Model Context Protocol (MCP) server that provides access to The Blue Alliance API for FIRST Robotics Competition data. Enables AI assistants and other MCP clients to retrieve comprehensive FRC team, event, and match information.
4
4
 
5
5
  ## Features
6
6
 
@@ -8,11 +8,13 @@ A Model Context Protocol (MCP) server that provides access to The Blue Alliance
8
8
  - **Event Data**: Access event details, rankings, matches, and elimination alliances
9
9
  - **Match Results**: Retrieve match data with scores, alliances, and breakdowns
10
10
  - **Historical Data**: Query data from 1992 to the current year
11
+ - **Type Safety**: All responses validated with Zod schemas
12
+ - **Comprehensive Coverage**: 35+ tools covering all major TBA API endpoints
11
13
 
12
14
  ## Prerequisites
13
15
 
14
16
  - Node.js 24
15
- - The Blue Alliance API key (register at [thebluealliance.com/account](https://www.thebluealliance.com/account))
17
+ - [The Blue Alliance](https://www.thebluealliance.com/) API key
16
18
 
17
19
  ## Installation
18
20
 
@@ -41,13 +43,13 @@ export TBA_API_KEY=your_api_key_here
41
43
 
42
44
  Or create a `.env` file:
43
45
 
44
- ```
46
+ ```bash
45
47
  TBA_API_KEY=your_api_key_here
46
48
  ```
47
49
 
48
50
  ## Usage
49
51
 
50
- Open up your application configuration, e.g. for Claude Desktop:
52
+ Add to your MCP client configuration (e.g., Claude Desktop):
51
53
 
52
54
  ```json
53
55
  {
@@ -65,550 +67,116 @@ Open up your application configuration, e.g. for Claude Desktop:
65
67
 
66
68
  ## Available Tools
67
69
 
68
- This MCP server provides many tools for accessing The Blue Alliance API. All tools validate input parameters and return structured, type-safe data.
69
-
70
- ### Team Information Tools
71
-
72
- #### Core Team Data
73
-
74
- - **`get_team`** - Get detailed team information
75
- - Parameters: `team_key` (string, format: frcXXXX)
76
- - Returns: Complete team profile including location, website, rookie year, motto
77
- - Example: `get_team(team_key="frc86")`
78
-
79
- - **`get_team_simple`** - Get simplified team information
80
- - Parameters: `team_key` (string, format: frcXXXX)
81
- - Returns: Basic team data (number, name, city, state, country)
82
-
83
- #### Team Participation & History
84
-
85
- - **`get_team_years_participated`** - Get years a team has participated in competition
86
- - Parameters: `team_key` (string)
87
- - Returns: Array of years (numbers)
88
-
89
- - **`get_team_districts`** - Get district history for a team
90
- - Parameters: `team_key` (string)
91
- - Returns: Array of district objects with abbreviation, display name, key, year
92
-
93
- - **`get_team_robots`** - Get robot names for a team by year
94
- - Parameters: `team_key` (string)
95
- - Returns: Array of robot objects with year, name, key
96
-
97
- - **`get_team_history`** - Get comprehensive historical data for a team
98
- - Parameters: `team_key` (string)
99
- - Returns: Awards, events, matches, and robots across all years
100
-
101
- #### Team Events & Performance
102
-
103
- - **`get_team_events`** - Get events a team participated in for a specific year
104
- - Parameters: `team_key` (string), `year` (number, 1992-current+1)
105
- - Returns: Array of detailed event objects
106
-
107
- - **`get_team_events_simple`** - Get simplified events for a team in a year
108
- - Parameters: `team_key` (string), `year` (number)
109
- - Returns: Array of basic event data
110
-
111
- - **`get_team_events_keys`** - Get event keys for a team in a year
112
- - Parameters: `team_key` (string), `year` (number)
113
- - Returns: Array of event key strings
114
-
115
- - **`get_team_events_all`** - Get all events a team has participated in across all years
116
- - Parameters: `team_key` (string)
117
- - Returns: Array of detailed event objects
118
-
119
- - **`get_team_event_status`** - Get team's rank and status at a specific event
120
- - Parameters: `team_key` (string), `event_key` (string)
121
- - Returns: Qualification ranking, alliance info, playoff status
122
-
123
- - **`get_team_event_statuses`** - Get team's status at all events in a year
124
- - Parameters: `team_key` (string), `year` (number)
125
- - Returns: Object mapping event keys to status objects
126
-
127
- #### Team Matches
128
-
129
- - **`get_team_matches`** - Get detailed matches for a team in a year
130
- - Parameters: `team_key` (string), `year` (number)
131
- - Returns: Array of complete match objects with scores, alliances, breakdowns
132
-
133
- - **`get_team_matches_simple`** - Get simplified matches for a team in a year
134
- - Parameters: `team_key` (string), `year` (number)
135
- - Returns: Array of basic match data
136
-
137
- - **`get_team_matches_keys`** - Get match keys for a team in a year
138
- - Parameters: `team_key` (string), `year` (number)
139
- - Returns: Array of match key strings
140
-
141
- - **`get_team_event_matches`** - Get detailed matches for a team at a specific event
142
- - Parameters: `team_key` (string), `event_key` (string)
143
- - Returns: Array of complete match objects
144
-
145
- - **`get_team_event_matches_simple`** - Get simplified matches for a team at an event
146
- - Parameters: `team_key` (string), `event_key` (string)
147
- - Returns: Array of basic match data
148
-
149
- - **`get_team_event_matches_keys`** - Get match keys for a team at an event
150
- - Parameters: `team_key` (string), `event_key` (string)
151
- - Returns: Array of match key strings
152
-
153
- #### Team Awards
154
-
155
- - **`get_team_awards`** - Get awards won by a team in a specific year
156
- - Parameters: `team_key` (string), `year` (number)
157
- - Returns: Array of award objects with name, type, event, recipients
158
-
159
- - **`get_team_awards_all`** - Get all awards won by a team across all years
160
- - Parameters: `team_key` (string)
161
- - Returns: Array of award objects
162
-
163
- - **`get_team_event_awards`** - Get awards won by a team at a specific event
164
- - Parameters: `team_key` (string), `event_key` (string)
165
- - Returns: Array of award objects
166
-
167
- #### Team Media & Social
168
-
169
- - **`get_team_media`** - Get media for a team in a specific year
170
- - Parameters: `team_key` (string), `year` (number)
171
- - Returns: Array of media objects (photos, videos, etc.)
172
-
173
- - **`get_team_media_by_tag`** - Get media for a team filtered by tag
174
- - Parameters: `team_key` (string), `media_tag` (string)
175
- - Returns: Array of filtered media objects
176
-
177
- - **`get_team_media_by_tag_year`** - Get media for a team by tag and year
178
- - Parameters: `team_key` (string), `media_tag` (string), `year` (number)
179
- - Returns: Array of filtered media objects
180
-
181
- - **`get_team_social_media`** - Get social media information for a team
182
- - Parameters: `team_key` (string)
183
- - Returns: Array of social media links and handles
184
-
185
- ### Event Information Tools
186
-
187
- #### Core Event Data
188
-
189
- - **`get_events`** - Get all FRC events for a specific year
190
- - Parameters: `year` (number, 1992-current+1)
191
- - Returns: Array of detailed event objects
192
-
193
- - **`get_events_simple`** - Get simplified events for a year
194
- - Parameters: `year` (number)
195
- - Returns: Array of basic event data
196
-
197
- - **`get_events_keys`** - Get event keys for a year
198
- - Parameters: `year` (number)
199
- - Returns: Array of event key strings
200
-
201
- - **`get_event`** - Get detailed information about a specific event
202
- - Parameters: `event_key` (string)
203
- - Returns: Complete event details including dates, location, webcasts
204
- - Example: `get_event(event_key="2023casj")`
205
-
206
- - **`get_event_simple`** - Get simplified event information
207
- - Parameters: `event_key` (string)
208
- - Returns: Basic event data
209
-
210
- #### Event Participants
211
-
212
- - **`get_event_teams`** - Get teams participating in an event
213
- - Parameters: `event_key` (string)
214
- - Returns: Array of detailed team objects
215
-
216
- - **`get_event_teams_simple`** - Get simplified teams in an event
217
- - Parameters: `event_key` (string)
218
- - Returns: Array of basic team data
219
-
220
- - **`get_event_teams_keys`** - Get team keys in an event
221
- - Parameters: `event_key` (string)
222
- - Returns: Array of team key strings
223
-
224
- #### Event Results & Rankings
225
-
226
- - **`get_event_rankings`** - Get team rankings for an event
227
- - Parameters: `event_key` (string)
228
- - Returns: Rankings object with team standings, records, statistics
229
-
230
- - **`get_event_alliances`** - Get elimination alliances for an event
231
- - Parameters: `event_key` (string)
232
- - Returns: Array of alliance objects with picks, status, records
233
-
234
- - **`get_event_awards`** - Get awards from a specific event
235
- - Parameters: `event_key` (string)
236
- - Returns: Array of award objects
237
-
238
- #### Event Matches
239
-
240
- - **`get_event_matches`** - Get detailed matches for an event
241
- - Parameters: `event_key` (string)
242
- - Returns: Array of complete match objects
243
-
244
- - **`get_event_matches_simple`** - Get simplified matches for an event
245
- - Parameters: `event_key` (string)
246
- - Returns: Array of basic match data
247
-
248
- - **`get_event_matches_keys`** - Get match keys for an event
249
- - Parameters: `event_key` (string)
250
- - Returns: Array of match key strings
251
-
252
- #### Event Analytics
253
-
254
- - **`get_event_insights`** - Get event-specific insights and statistics
255
- - Parameters: `event_key` (string)
256
- - Returns: Qualification and playoff statistics and insights
257
-
258
- - **`get_event_oprs`** - Get OPR, DPR, and CCWM ratings for teams at an event
259
- - Parameters: `event_key` (string)
260
- - Returns: Object with OPR (Offensive Power Rating), DPR (Defensive Power Rating), CCWM (Calculated Contribution to Winning Margin)
261
-
262
- - **`get_event_predictions`** - Get TBA-generated predictions for an event
263
- - Parameters: `event_key` (string)
264
- - Returns: Match and ranking predictions
265
-
266
- - **`get_event_district_points`** - Get district points for teams at an event
267
- - Parameters: `event_key` (string)
268
- - Returns: District points breakdown by team
269
-
270
- ### Match Information Tools
271
-
272
- - **`get_match`** - Get detailed information about a specific match
273
- - Parameters: `match_key` (string)
274
- - Returns: Complete match data with scores, alliances, breakdown
275
- - Example: `get_match(match_key="2023casj_qm1")`
276
-
277
- - **`get_match_simple`** - Get simplified match information
278
- - Parameters: `match_key` (string)
279
- - Returns: Basic match data
280
-
281
- - **`get_match_zebra`** - Get Zebra MotionWorks data for a match (robot tracking)
282
- - Parameters: `match_key` (string)
283
- - Returns: Robot position tracking data (if available)
70
+ ### Team Information (24 tools)
284
71
 
285
- ### District Tools
72
+ Access comprehensive team data including profiles, participation history, events, matches, awards, and media.
286
73
 
287
- - **`get_districts`** - Get all districts for a specific year
288
- - Parameters: `year` (number)
289
- - Returns: Array of district objects
74
+ **Key tools**: `get_team`, `get_team_events`, `get_team_matches`, `get_team_awards`, `get_team_media`
290
75
 
291
- - **`get_district_rankings`** - Get team rankings within a district
292
- - Parameters: `district_key` (string)
293
- - Returns: Array of district ranking objects with points breakdown
294
- - Example: `get_district_rankings(district_key="2023fim")`
76
+ [View all team tools →](docs/TOOLS.md#team-information-tools)
295
77
 
296
- - **`get_district_events`** - Get events in a specific district
297
- - Parameters: `district_key` (string)
298
- - Returns: Array of detailed event objects
78
+ ### Event Information (19 tools)
299
79
 
300
- - **`get_district_events_simple`** - Get simplified events in a district
301
- - Parameters: `district_key` (string)
302
- - Returns: Array of basic event data
80
+ Query event details, participants, rankings, matches, and analytics.
303
81
 
304
- - **`get_district_events_keys`** - Get event keys in a district
305
- - Parameters: `district_key` (string)
306
- - Returns: Array of event key strings
82
+ **Key tools**: `get_event`, `get_events`, `get_event_teams`, `get_event_rankings`, `get_event_matches`, `get_event_oprs`
307
83
 
308
- - **`get_district_teams`** - Get teams in a specific district
309
- - Parameters: `district_key` (string)
310
- - Returns: Array of detailed team objects
84
+ [View all event tools →](docs/TOOLS.md#event-information-tools)
311
85
 
312
- - **`get_district_teams_simple`** - Get simplified teams in a district
313
- - Parameters: `district_key` (string)
314
- - Returns: Array of basic team data
86
+ ### Match Information (3 tools)
315
87
 
316
- - **`get_district_teams_keys`** - Get team keys in a district
317
- - Parameters: `district_key` (string)
318
- - Returns: Array of team key strings
88
+ Retrieve detailed match data including scores, alliances, and robot tracking.
319
89
 
320
- ### General/Utility Tools
90
+ **Key tools**: `get_match`, `get_match_simple`, `get_match_zebra`
321
91
 
322
- - **`get_teams`** - Get paginated list of all teams (detailed)
323
- - Parameters: `page_num` (number, 0-indexed)
324
- - Returns: Array of complete team objects (500 teams per page)
92
+ [View all match tools →](docs/TOOLS.md#match-information-tools)
325
93
 
326
- - **`get_teams_simple`** - Get paginated list of teams (simplified)
327
- - Parameters: `page_num` (number, 0-indexed)
328
- - Returns: Array of basic team data
94
+ ### District Tools (8 tools)
329
95
 
330
- - **`get_teams_keys`** - Get paginated list of team keys
331
- - Parameters: `page_num` (number, 0-indexed)
332
- - Returns: Array of team key strings
96
+ Access district rankings, events, and team information.
333
97
 
334
- - **`get_teams_by_year`** - Get teams that competed in a specific year (detailed)
335
- - Parameters: `year` (number), `page_num` (number, 0-indexed)
336
- - Returns: Array of complete team objects
98
+ **Key tools**: `get_districts`, `get_district_rankings`, `get_district_events`, `get_district_teams`
337
99
 
338
- - **`get_teams_by_year_simple`** - Get teams from a year (simplified)
339
- - Parameters: `year` (number), `page_num` (number, 0-indexed)
340
- - Returns: Array of basic team data
100
+ [View all district tools →](docs/TOOLS.md#district-tools)
341
101
 
342
- - **`get_teams_by_year_keys`** - Get team keys from a specific year
343
- - Parameters: `year` (number), `page_num` (number, 0-indexed)
344
- - Returns: Array of team key strings
102
+ ### General/Utility Tools (6 tools)
345
103
 
346
- - **`get_status`** - Get TBA API status information
347
- - No parameters required
348
- - Returns: API status including current season, downtime info, app versions
104
+ Paginated team listings and API status information.
349
105
 
350
- ### Parameter Validation
106
+ **Key tools**: `get_teams`, `get_teams_by_year`, `get_status`
351
107
 
352
- All tools implement strict parameter validation:
108
+ [View all utility tools →](docs/TOOLS.md#generalutility-tools)
353
109
 
354
- - **Team Keys**: Must match format `frcXXXX` (e.g., `frc86`, `frc1234`)
355
- - **Years**: Must be between 1992 and current year + 1
356
- - **Event Keys**: String format like `2023casj`, `2024week1`
357
- - **Match Keys**: String format like `2023casj_qm1`, `2024week1_sf1m1`
358
- - **District Keys**: String format like `2023fim`, `2024pnw`
359
- - **Page Numbers**: 0-indexed integers (≥ 0)
110
+ ### Complete Documentation
360
111
 
361
- ### Data Response Formats
112
+ - **[All Tools](docs/TOOLS.md)** - Complete reference for all 35+ tools with parameters and examples
113
+ - **[Data Schemas](docs/SCHEMAS.md)** - Detailed schema documentation for all response types
114
+ - **[Development Guide](docs/DEVELOPMENT.md)** - Building, testing, and contributing
362
115
 
363
- - **Simple**: Basic information for lists and overviews
364
- - **Detailed**: Complete information including all available fields
365
- - **Keys**: Just the identifier strings for efficient lookups
116
+ ## Quick Examples
366
117
 
367
- ### Common Patterns
118
+ ### Get team information
368
119
 
369
- **Find a team's performance at a specific event:**
120
+ ```typescript
121
+ // Get detailed team profile
122
+ get_team(team_key: "frc86")
370
123
 
371
- 1. Use `get_team_event_matches` to get their matches
372
- 2. Use `get_event_rankings` to see their final ranking
124
+ // Get team's events in a year
125
+ get_team_events(team_key: "frc86", year: 2024)
373
126
 
374
- **Analyze an event:**
375
-
376
- 1. Use `get_event` for basic event info
377
- 2. Use `get_event_teams` to see participating teams
378
- 3. Use `get_event_rankings` for final standings
379
- 4. Use `get_event_alliances` for elimination results
380
-
381
- ## Development
382
-
383
- ### Building
384
-
385
- ```bash
386
- npm run build
127
+ // Get team's awards
128
+ get_team_awards(team_key: "frc86", year: 2024)
387
129
  ```
388
130
 
389
- ### Testing
390
-
391
- #### Unit Tests (Jest)
131
+ ### Analyze an event
392
132
 
393
- ```bash
394
- npm test # Run unit tests
395
- npm run test:watch # Run unit tests in watch mode
396
- ```
397
-
398
- #### Integration Tests (Playwright)
133
+ ```typescript
134
+ // Get event details
135
+ get_event(event_key: "2024casj")
399
136
 
400
- ```bash
401
- npm run test:integration # Run all integration tests
402
- npm run test:integration:ui # Run with Playwright UI
403
- npm run test:integration:debug # Debug mode
404
- ```
137
+ // Get participating teams
138
+ get_event_teams(event_key: "2024casj")
405
139
 
406
- #### All Tests
140
+ // Get rankings
141
+ get_event_rankings(event_key: "2024casj")
407
142
 
408
- ```bash
409
- npm run test:all # Run both unit and integration tests
143
+ // Get elimination alliances
144
+ get_event_alliances(event_key: "2024casj")
410
145
  ```
411
146
 
412
- **Note**: Integration tests require a valid TBA API key set as `TBA_API_KEY` environment variable.
147
+ ### Get match data
413
148
 
414
- ### Linting
149
+ ```typescript
150
+ // Get detailed match information
151
+ get_match(match_key: "2024casj_qm1")
415
152
 
416
- ```bash
417
- npm run lint
418
- npm run lint:fix
153
+ // Get robot tracking data (if available)
154
+ get_match_zebra(match_key: "2024casj_qm1")
419
155
  ```
420
156
 
421
- ### Development Workflow
422
-
423
- ```bash
424
- # Install dependencies
425
- npm ci
157
+ ## Development
426
158
 
427
- # Run unit tests in watch mode during development
428
- npm run test:watch
159
+ See the [Development Guide](docs/DEVELOPMENT.md) for detailed instructions on:
429
160
 
430
- # Build the project
431
- npm run build
161
+ - Building and testing
162
+ - Adding new tools
163
+ - Running unit and integration tests
164
+ - Code standards and contribution guidelines
432
165
 
433
- # Run all tests (unit + integration)
434
- npm run test:all
166
+ Quick start:
435
167
 
436
- # Test with the MCP inspector
437
- npm run inspect
168
+ ```bash
169
+ npm ci # Install dependencies
170
+ npm run build # Build TypeScript
171
+ npm test # Run unit tests
172
+ npm run test:integration # Run integration tests
173
+ npm run lint # Check code quality
174
+ npm run inspect # Launch MCP inspector
438
175
  ```
439
176
 
440
- ## Data Schemas
441
-
442
- All API responses are validated using Zod schemas ensuring type safety and consistency:
443
-
444
- ### Core Schemas
445
-
446
- #### Team Schema
447
-
448
- Complete team information including:
449
-
450
- - `key` (string) - Team identifier (e.g., "frc86")
451
- - `team_number` (number) - Numeric team number
452
- - `nickname` (string) - Team nickname/informal name
453
- - `name` (string) - Official team name
454
- - `city`, `state_prov`, `country` (string) - Location details
455
- - `website` (string) - Team website URL
456
- - `rookie_year` (number) - First year of competition
457
- - `motto` (string) - Team motto/slogan
458
- - Location data: `lat`, `lng`, `address`, `postal_code`, `gmaps_place_id`, `gmaps_url`
459
-
460
- #### TeamSimple Schema
461
-
462
- Simplified team data:
463
-
464
- - `key`, `team_number`, `nickname`, `name`
465
- - `city`, `state_prov`, `country`
466
-
467
- #### Event Schema
468
-
469
- Complete event information including:
470
-
471
- - `key` (string) - Event identifier (e.g., "2023casj")
472
- - `name` (string) - Official event name
473
- - `event_code` (string) - Short event code
474
- - `event_type` (number) - Event type identifier
475
- - `start_date`, `end_date` (string) - ISO date strings
476
- - `year` (number) - Competition year
477
- - `week` (number) - Competition week (null for offseason)
478
- - Location: `city`, `state_prov`, `country`, `address`, `timezone`
479
- - `district` - District information object (if applicable)
480
- - `webcasts` - Array of webcast objects with type, channel, date
481
- - `playoff_type`, `playoff_type_string` - Playoff format information
482
-
483
- #### EventSimple Schema
484
-
485
- Basic event data:
486
-
487
- - `key`, `name`, `event_code`, `event_type`
488
- - `city`, `state_prov`, `country`
489
- - `start_date`, `end_date`, `year`
490
-
491
- #### Match Schema
492
-
493
- Complete match information:
494
-
495
- - `key` (string) - Match identifier (e.g., "2023casj_qm1")
496
- - `comp_level` (string) - Competition level (qm, ef, qf, sf, f)
497
- - `set_number`, `match_number` (number) - Match identifiers
498
- - `alliances` - Red and blue alliance objects containing:
499
- - `score` (number) - Alliance final score
500
- - `team_keys` (string[]) - Array of team identifiers
501
- - `surrogate_team_keys`, `dq_team_keys` (string[]) - Special designations
502
- - `winning_alliance` (string) - "red", "blue", or null for ties
503
- - `event_key` (string) - Parent event identifier
504
- - Timing: `time`, `actual_time`, `predicted_time`, `post_result_time`
505
- - `score_breakdown` - Detailed scoring breakdown object (game-specific)
506
- - `videos` - Array of video objects with type and key
507
-
508
- #### MatchSimple Schema
509
-
510
- Basic match data:
511
-
512
- - `key`, `comp_level`, `set_number`, `match_number`
513
- - Simplified `alliances` with score and team_keys only
514
- - `winning_alliance`, `event_key`
515
- - Basic timing: `time`, `predicted_time`, `actual_time`
516
-
517
- #### Award Schema
518
-
519
- Award information:
520
-
521
- - `name` (string) - Award name
522
- - `award_type` (number) - Award type identifier
523
- - `event_key` (string) - Event where awarded
524
- - `year` (number) - Competition year
525
- - `recipient_list` - Array of recipient objects:
526
- - `team_key` (string) - Team recipient (if applicable)
527
- - `awardee` (string) - Individual recipient (if applicable)
528
-
529
- #### Rankings Schema
530
-
531
- Event ranking information:
532
-
533
- - `rankings` - Array of ranking objects:
534
- - `team_key` (string) - Team identifier
535
- - `rank` (number) - Current ranking position
536
- - `matches_played` (number) - Number of matches played
537
- - `record` - Win/loss/tie record object
538
- - `qual_average` (number) - Average qualification score
539
- - `extra_stats` (number[]) - Additional statistics
540
- - `sort_orders` (number[]) - Tiebreaker values
541
- - `extra_stats_info`, `sort_order_info` - Metadata describing statistics
542
-
543
- #### Alliance Schema
544
-
545
- Elimination alliance information:
546
-
547
- - `name` (string) - Alliance name/number
548
- - `picks` (string[]) - Array of team keys in pick order
549
- - `backup` - Backup team information (if applicable)
550
- - `declines` (string[]) - Teams that declined alliance invitations
551
- - `status` - Alliance performance object:
552
- - `level` (string) - Current playoff level
553
- - `status` (string) - Current status
554
- - `record` - Overall playoff record
555
- - `current_level_record` - Record at current level
556
- - `playoff_average` (number) - Average playoff score
557
-
558
- #### Additional Schemas
559
-
560
- - **District Schema**: District information with abbreviation, display name, key, year
561
- - **Robot Schema**: Robot information with year, name, key, team_key
562
- - **Media Schema**: Media objects with type, foreign_key, details, URLs
563
- - **DistrictPoints Schema**: District points breakdown by team
564
- - **DistrictRanking Schema**: District standings with point totals and event breakdown
565
- - **TeamEventStatus Schema**: Team status at specific events (qualification rank, alliance, playoff status)
566
- - **Insights Schema**: Event-specific statistics and insights
567
- - **EventOPRs Schema**: OPR, DPR, and CCWM ratings
568
- - **Zebra Schema**: Robot tracking data with position coordinates over time
569
- - **Prediction Schema**: TBA-generated match and ranking predictions
570
- - **Status Schema**: API status information
571
-
572
- ### Schema Validation
573
-
574
- All responses are validated to ensure:
575
-
576
- - **Type Safety**: Correct data types for all fields
577
- - **Required Fields**: Essential data is always present
578
- - **Null Handling**: Proper handling of optional/missing data
579
- - **Consistency**: Uniform structure across all endpoints
580
- - **Error Prevention**: Invalid data is caught before reaching your application
581
-
582
- ## Error Handling
583
-
584
- The server provides detailed error messages for:
585
-
586
- - Missing or invalid API keys
587
- - Invalid team keys (must be format `frcXXXX`)
588
- - Invalid years (must be 1992 to current year + 1)
589
- - TBA API errors (rate limits, not found, etc.)
590
- - Schema validation failures
591
-
592
- ## API Rate Limits
593
-
594
- The Blue Alliance API has rate limits. The server will pass through any rate limiting errors from the TBA API. Consider implementing request caching or throttling in your client application for heavy usage.
595
-
596
- ## Contributing
597
-
598
- 1. Fork the repository
599
- 2. Create a feature branch
600
- 3. Make your changes
601
- 4. Add tests for new functionality
602
- 5. Run the test suite
603
- 6. Submit a pull request
604
-
605
- ## License
606
-
607
- MIT License - see [LICENSE](LICENSE) file for details.
608
-
609
177
  ## Related Links
610
178
 
611
179
  - [The Blue Alliance](https://www.thebluealliance.com/) - Official FRC data source
612
180
  - [TBA API Documentation](https://www.thebluealliance.com/apidocs/v3) - Official API docs
613
- - [Model Context Protocol](https://spec.modelcontextprotocol.io/) - MCP specification
181
+ - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
614
182
  - [FIRST Robotics Competition](https://www.firstinspires.org/robotics/frc) - Official FRC site
package/dist/index.js CHANGED
@@ -20,7 +20,7 @@ async function runServer() {
20
20
  }
21
21
  server = new Server({
22
22
  name: 'The Blue Alliance MCP Server',
23
- version: '1.0.1',
23
+ version: '1.0.3',
24
24
  }, {
25
25
  capabilities: {
26
26
  tools: {},
package/package.json CHANGED
@@ -2,11 +2,11 @@
2
2
  "type": "module",
3
3
  "name": "@withinfocus/tba-mcp-server",
4
4
  "mcpName": "io.github.withinfocus/tba",
5
- "version": "1.0.1",
5
+ "version": "1.0.3",
6
6
  "description": "The Blue Alliance MCP Server",
7
7
  "repository": {
8
8
  "type": "git",
9
- "url": "git+https://github.com/withinfocus/tba-mcp-server.git"
9
+ "url": "https://github.com/withinfocus/tba-mcp-server"
10
10
  },
11
11
  "author": "Matt Bishop <matt@withinfocus.com>",
12
12
  "license": "MIT",
@@ -14,14 +14,14 @@
14
14
  "url": "https://github.com/withinfocus/tba-mcp-server/issues"
15
15
  },
16
16
  "dependencies": {
17
- "@modelcontextprotocol/sdk": "1.24.3",
17
+ "@modelcontextprotocol/sdk": "1.25.1",
18
18
  "shx": "0.4.0",
19
19
  "zod": "4.2.1"
20
20
  },
21
21
  "devDependencies": {
22
22
  "@eslint/js": "9.39.2",
23
23
  "@jest/globals": "30.2.0",
24
- "@modelcontextprotocol/inspector": "0.17.5",
24
+ "@modelcontextprotocol/inspector": "0.18.0",
25
25
  "@playwright/test": "1.57.0",
26
26
  "@types/jest": "30.0.0",
27
27
  "@types/node": "24.10.4",
@@ -34,7 +34,7 @@
34
34
  "prettier": "3.7.4",
35
35
  "ts-jest": "29.4.6",
36
36
  "typescript": "5.9.3",
37
- "typescript-eslint": "8.50.0"
37
+ "typescript-eslint": "8.50.1"
38
38
  },
39
39
  "bin": {
40
40
  "mcp-server-tba": "dist/index.js"