speechwire-mcp 0.1.0__tar.gz

speechwire_mcp-0.1.0/.env.example

@@ -0,0 +1,6 @@
+SPEECHWIRE_EMAIL=
+SPEECHWIRE_PASSWORD=
+# Optional — omit to use discovery mode:
+# SPEECHWIRE_ACCOUNT_ID=
+# SPEECHWIRE_CIRCUIT_ID=
+# SPEECHWIRE_TOURNAMENT_ID=

speechwire_mcp-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,127 @@
+# Copilot Instructions for SpeechWireMCP
+
+## Project Overview
+
+SpeechWireMCP is a Model Context Protocol (MCP) server that gives AI assistants
+secure access to SpeechWire tournament judge data for speech-and-debate
+(forensics) competitions. It scrapes manage.speechwire.com behind an
+authenticated session and exposes structured data through MCP tools.
+
+## Tech Stack
+
+- **Python 3.11+** — use modern syntax (`X | Y` unions, `list[dict]`, etc.)
+- **MCP SDK** (`mcp` package, `FastMCP`) — tool registration via `@mcp.tool()`
+- **requests** — HTTP client with a stateful `requests.Session` for auth cookies
+- **BeautifulSoup4** — HTML parsing of SpeechWire pages
+- **Hatchling** — PEP 517 build backend
+- **pytest** — testing
+- **ruff** — linting (line-length 100, target py311)
+
+## Architecture
+
+```
+src/speechwire_mcp/
+├── server.py            # FastMCP server, tool definitions, lazy client init
+├── client.py            # SpeechWireClient (4-step auth), _fetch_and_parse helper
+├── parsing_helpers.py   # Shared BS4 utilities (make_soup, td_safe, extract_int_query_param)
+├── judges/
+│   ├── client.py        # Judge data retrieval (list, contact, availability, school)
+│   └── parsers.py       # Judge HTML → structured data parsing
+├── login/
+│   ├── client.py        # Account & tournament discovery after login
+│   └── parsers.py       # Account list & tournament list parsing
+├── rooms/
+│   ├── client.py        # Room list, usage grid, count retrieval
+│   └── parsers.py       # Room HTML → structured data parsing
+├── results/
+│   ├── client.py        # Tab sheet results retrieval
+│   └── parsers.py       # Results HTML → structured data parsing
+├── schematics/
+│   ├── client.py        # Schematic event list & round schematic retrieval
+│   └── parsers.py       # Schematic HTML → structured data parsing
+├── structure/
+│   ├── client.py        # Timeslot & grouping retrieval
+│   └── parsers.py       # Schedule/grouping HTML → structured data parsing
+└── teams/
+    ├── client.py        # Team list, entries, hybrid entries retrieval
+    └── parsers.py       # Team HTML → structured data parsing
+```
+
+- **server.py** is the MCP entry point. Tools are thin wrappers that delegate to
+  domain modules (`judges/`, `login/`, `rooms/`, `results/`, `schematics/`,
+  `structure/`, `teams/`).
+- **client.py** owns all HTTP and authentication logic. The client automatically
+  re-authenticates when it detects a session expiry.
+- **parsing_helpers.py** provides shared BeautifulSoup utilities used by all
+  domain parsers.
+- Each **domain module** follows the same pattern: `client.py` calls
+  `_fetch_and_parse` with a URL and parser; `parsers.py` contains pure functions
+  that take HTML strings and return dicts/lists — keep them side-effect free for
+  easy testing.
+- **`_fetch_and_parse`** is the shared pattern: fetch a page, run a parser,
+  return a safe default on any failure. Accepts an optional `params` dict for
+  query parameters — prefer `params={"key": "val"}` over f-string URL
+  interpolation.
+
+## Conventions
+
+- **Error handling:** never raise from MCP tools. Log errors and return sensible
+  defaults (empty list, `None`, etc.) so the AI client always gets a valid
+  response.
+- **Logging:** use `logging.getLogger(__name__)` in every module.
+- **No real PII in code or tests:** never use real names, emails, phone
+  numbers, or other personally identifiable information anywhere in the
+  repository. All test data must use the fictional West Wing characters and
+  schools defined in `tests/fake_data.py`. Import constants from that module
+  rather than inventing new names inline. Use the `email_for()` helper for
+  fake email addresses (all `@example.com`).
+- **Type hints:** annotate all public functions. Use built-in generics
+  (`list`, `dict`, `str | None`) — no `typing.List`/`typing.Optional`.
+- **Docstrings:** use NumPy-style docstrings (`Parameters`, `Returns` sections).
+- **Line length:** 100 characters max (enforced by ruff).
+- **URL construction:** use `params={"key": "val"}` in `_fetch_and_parse`
+  calls rather than f-string interpolation to prevent injection risks.
+- **Tests:** parser functions get unit tests in `tests/` with sample HTML
+  fixtures. Use `pytest`.
+
+## Environment Variables
+
+The server requires these at runtime (never hard-code credentials):
+
+| Variable | Purpose |
+|----------|---------|
+| `SPEECHWIRE_EMAIL` | Account email |
+| `SPEECHWIRE_PASSWORD` | Account password |
+| `SPEECHWIRE_ACCOUNT_ID` | Numeric account ID |
+| `SPEECHWIRE_CIRCUIT_ID` | Numeric circuit ID |
+| `SPEECHWIRE_TOURNAMENT_ID` | Numeric tournament ID |
+| `SPEECHWIRE_MCP_TRANSPORT` | `stdio` (default) or `sse` |
+| `SPEECHWIRE_MCP_HOST` | SSE bind host (default `127.0.0.1`) |
+| `SPEECHWIRE_MCP_PORT` | SSE bind port (default `8080`) |
+
+## Development Workflow
+
+```bash
+pip install -e ".[dev]"   # editable install with dev deps
+ruff check src/ tests/     # lint
+pytest                     # test
+```
+
+CI runs on Python 3.11, 3.12, and 3.13. Publishing to PyPI is triggered by
+pushing a `v*` tag.
+
+## Adding a New MCP Tool
+
+1. Add a parser in `<domain>/parsers.py` (pure function, HTML → data).
+2. Add a retrieval function in `<domain>/client.py` using `_fetch_and_parse`.
+3. Export it from `<domain>/__init__.py`.
+4. Register the tool in `server.py` with `@mcp.tool()` and a clear docstring.
+5. Write parser tests in `tests/`.
+
+## Process
+
+- **Never make git commits or push branches without explicit permission.**
+- **Do not add new dependencies** (packages, libraries, tools) without asking
+  first.
+- **Run `ruff check src/ tests/` and `pytest`** before declaring work complete.
+- **Do not modify files outside `src/` and `tests/`** without asking first.

speechwire_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/ tests/
+      - run: pytest

speechwire_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,87 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/ tests/
+      - run: pytest
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Check if tag is on dev
+        id: check
+        run: |
+          if git branch -r --contains "${{ github.ref_name }}" | grep -q 'origin/dev'; then
+            echo "on_dev=true" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: actions/download-artifact@v4
+        if: steps.check.outputs.on_dev == 'true'
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        if: steps.check.outputs.on_dev == 'true'
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Check if tag is on main
+        id: check
+        run: |
+          if git branch -r --contains "${{ github.ref_name }}" | grep -q 'origin/main'; then
+            echo "on_main=true" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: actions/download-artifact@v4
+        if: steps.check.outputs.on_main == 'true'
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        if: steps.check.outputs.on_main == 'true'
+

speechwire_mcp-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# OS files
+.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+
+# Environment files
+.env
+.env.local
+
+# pytest / ruff cache
+.pytest_cache/
+.ruff_cache/
+
+# Notebooks (may contain credentials)
+notebooks/
+*.ipynb
+
+# Copilot
+.copilot/

speechwire_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jessica Moore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

speechwire_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: speechwire-mcp
+Version: 0.1.0
+Summary: Model Context Protocol (MCP) server for interacting with SpeechWire tournament management
+Project-URL: Homepage, https://github.com/jessica-writes-code/speechwire-mcp
+Project-URL: Repository, https://github.com/jessica-writes-code/speechwire-mcp
+Project-URL: Issues, https://github.com/jessica-writes-code/speechwire-mcp/issues
+Author: Jessica Moore
+License-Expression: MIT
+License-File: LICENSE
+Keywords: forensics,mcp,model-context-protocol,speech-and-debate,speechwire
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4<5.0,>=4.12.0
+Requires-Dist: mcp<2.0,>=1.0.0
+Requires-Dist: requests<3.0,>=2.32.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SpeechWire MCP Server
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.11%2B-blue)](#) [![PyPI](https://img.shields.io/pypi/v/speechwire-mcp)](#)
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that provides AI assistants with secure, authenticated access to [SpeechWire](https://www.speechwire.com/) tournament data for speech-and-debate (forensics) competitions.
+
+The server scrapes manage.speechwire.com behind an authenticated session and exposes structured tournament data through MCP tools, enabling AI assistants to help tournament directors manage judge assignments, rooms, teams, entries, and round pairings.
+
+## Features
+
+- **Judge management** — list judges, contact info, availability, school associations, judge types, and add new judges
+- **Team & entry data** — team rosters, entries by team, hybrid/cross-school entries
+- **Room management** — room lists, usage grids, room-vs-section counts
+- **Schematics** — event lists, round-by-round pairings with judges, rooms, and competitors
+- **Tournament structure** — timeslots, competition groupings
+- **Results** — tab sheets with round outcomes, speaker scores, and placements
+- **Account discovery** — list and select accounts and tournaments interactively
+- **Session management** — automatic re-authentication on session expiry
+
+## Installation
+
+```bash
+pip install speechwire-mcp
+```
+
+Set your SpeechWire credentials as environment variables:
+
+```bash
+export SPEECHWIRE_EMAIL="your-email@example.com"
+export SPEECHWIRE_PASSWORD="your-password"
+```
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `speechwire_list_user_accounts` | List accounts available after login |
+| `speechwire_select_user_account` | Select an account to work with |
+| `speechwire_list_user_tournaments` | List tournaments for the selected account |
+| `speechwire_select_user_tournament` | Select a tournament to activate |
+| `speechwire_list_judges` | List all judges with roster details |
+| `speechwire_get_judge_contact` | Get judge email and phone |
+| `speechwire_get_judge_availability` | Get judge availability by timeslot |
+| `speechwire_get_judge_school` | Get judge's school association |
+| `speechwire_add_judge` | Add a new judge to the tournament |
+| `speechwire_update_judge_email` | Update a judge's email address |
+| `speechwire_update_judge_availability` | Update a judge's availability slots |
+| `speechwire_update_judge_school` | Update a judge's school/team affiliation |
+| `speechwire_list_judge_types` | List configured judge types |
+| `speechwire_list_rooms` | List tournament rooms |
+| `speechwire_get_room_usage` | Get room time-slot usage grid |
+| `speechwire_get_room_counts` | Get rooms vs. sections per grouping/round |
+| `speechwire_list_teams` | List registered teams |
+| `speechwire_get_team_entries` | Get entries for a specific team |
+| `speechwire_list_hybrid_entries` | List cross-school hybrid entries |
+| `speechwire_list_timeslots` | List tournament schedule timeslots |
+| `speechwire_list_groupings` | List competition groupings |
+| `speechwire_list_schematic_events` | List schematic events with available rounds |
+| `speechwire_get_round_schematic` | Get pairings for a specific event round |
+| `speechwire_get_tab_sheet` | Get results tab sheet for a grouping |
+
+## License
+
+[MIT](LICENSE)

speechwire_mcp-0.1.0/README.md

@@ -0,0 +1,64 @@
+# SpeechWire MCP Server
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.11%2B-blue)](#) [![PyPI](https://img.shields.io/pypi/v/speechwire-mcp)](#)
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that provides AI assistants with secure, authenticated access to [SpeechWire](https://www.speechwire.com/) tournament data for speech-and-debate (forensics) competitions.
+
+The server scrapes manage.speechwire.com behind an authenticated session and exposes structured tournament data through MCP tools, enabling AI assistants to help tournament directors manage judge assignments, rooms, teams, entries, and round pairings.
+
+## Features
+
+- **Judge management** — list judges, contact info, availability, school associations, judge types, and add new judges
+- **Team & entry data** — team rosters, entries by team, hybrid/cross-school entries
+- **Room management** — room lists, usage grids, room-vs-section counts
+- **Schematics** — event lists, round-by-round pairings with judges, rooms, and competitors
+- **Tournament structure** — timeslots, competition groupings
+- **Results** — tab sheets with round outcomes, speaker scores, and placements
+- **Account discovery** — list and select accounts and tournaments interactively
+- **Session management** — automatic re-authentication on session expiry
+
+## Installation
+
+```bash
+pip install speechwire-mcp
+```
+
+Set your SpeechWire credentials as environment variables:
+
+```bash
+export SPEECHWIRE_EMAIL="your-email@example.com"
+export SPEECHWIRE_PASSWORD="your-password"
+```
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `speechwire_list_user_accounts` | List accounts available after login |
+| `speechwire_select_user_account` | Select an account to work with |
+| `speechwire_list_user_tournaments` | List tournaments for the selected account |
+| `speechwire_select_user_tournament` | Select a tournament to activate |
+| `speechwire_list_judges` | List all judges with roster details |
+| `speechwire_get_judge_contact` | Get judge email and phone |
+| `speechwire_get_judge_availability` | Get judge availability by timeslot |
+| `speechwire_get_judge_school` | Get judge's school association |
+| `speechwire_add_judge` | Add a new judge to the tournament |
+| `speechwire_update_judge_email` | Update a judge's email address |
+| `speechwire_update_judge_availability` | Update a judge's availability slots |
+| `speechwire_update_judge_school` | Update a judge's school/team affiliation |
+| `speechwire_list_judge_types` | List configured judge types |
+| `speechwire_list_rooms` | List tournament rooms |
+| `speechwire_get_room_usage` | Get room time-slot usage grid |
+| `speechwire_get_room_counts` | Get rooms vs. sections per grouping/round |
+| `speechwire_list_teams` | List registered teams |
+| `speechwire_get_team_entries` | Get entries for a specific team |
+| `speechwire_list_hybrid_entries` | List cross-school hybrid entries |
+| `speechwire_list_timeslots` | List tournament schedule timeslots |
+| `speechwire_list_groupings` | List competition groupings |
+| `speechwire_list_schematic_events` | List schematic events with available rounds |
+| `speechwire_get_round_schematic` | Get pairings for a specific event round |
+| `speechwire_get_tab_sheet` | Get results tab sheet for a grouping |
+
+## License
+
+[MIT](LICENSE)

speechwire_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "speechwire-mcp"
+version = "0.1.0"
+description = "Model Context Protocol (MCP) server for interacting with SpeechWire tournament management"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Jessica Moore" },
+]
+keywords = ["speechwire", "mcp", "model-context-protocol", "speech-and-debate", "forensics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.0.0,<2.0",
+    "requests>=2.32.0,<3.0",
+    "beautifulsoup4>=4.12.0,<5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.4.0",
+]
+
+[project.scripts]
+speechwire-mcp = "speechwire_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/jessica-writes-code/speechwire-mcp"
+Repository = "https://github.com/jessica-writes-code/speechwire-mcp"
+Issues = "https://github.com/jessica-writes-code/speechwire-mcp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/speechwire_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100

speechwire_mcp-0.1.0/src/speechwire_mcp/__init__.py

@@ -0,0 +1,37 @@
+"""speechwire-mcp: Model Context Protocol server for SpeechWire tournament management."""
+
+from speechwire_mcp.client import SpeechWireClient, SpeechWireAuthError
+from speechwire_mcp.judges import (
+    get_judge_list,
+    get_judge_contact,
+    get_judge_availability,
+    get_judge_school,
+)
+from speechwire_mcp.login import get_accounts, get_tournaments
+from speechwire_mcp.rooms import get_room_counts, get_room_list, get_room_usage
+from speechwire_mcp.schematics import get_schematic_events, get_round_schematic
+from speechwire_mcp.structure import get_groupings, get_timeslots
+from speechwire_mcp.teams import get_team_list, get_team_entries, get_hybrid_entries
+from speechwire_mcp.results import get_tab_sheet
+
+__all__ = [
+    "SpeechWireClient",
+    "SpeechWireAuthError",
+    "get_judge_list",
+    "get_judge_contact",
+    "get_judge_availability",
+    "get_judge_school",
+    "get_accounts",
+    "get_tournaments",
+    "get_room_counts",
+    "get_room_list",
+    "get_room_usage",
+    "get_schematic_events",
+    "get_round_schematic",
+    "get_groupings",
+    "get_timeslots",
+    "get_team_list",
+    "get_team_entries",
+    "get_hybrid_entries",
+    "get_tab_sheet",
+]

speechwire_mcp-0.1.0/src/speechwire_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Run the SpeechWire MCP server: python -m speechwire_mcp"""
+
+from speechwire_mcp.server import main
+
+main()