# fishernick/brightspacemcp architecture

> Architecture diagram of the GitHub repository fishernick/brightspacemcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fishernick/brightspacemcp
- Repository: https://github.com/fishernick/brightspacemcp

## Overview

Brightspace-MCP exposes one Brightspace account as authenticated MCP tools, with a companion browser-cookie synchronization path that keeps outbound LMS access current. The main user workflow is an MCP client requesting account, course, grade, content, or due-work data; the server fetches and shapes Brightspace responses. README documents additional tool families not fully visible in the sampled server excerpt, so those are represented at the server-module level; exact internal wiring is shown only where supported.

Main entry points: [`src/brightspacemcp/server.py`](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py) (API requester), [`cookie_sync_server.py`](https://github.com/fishernick/brightspacemcp/blob/master/cookie_sync_server.py) (Cookie receiver), [`extension/background.js`](https://github.com/fishernick/brightspacemcp/blob/master/extension/background.js) (Cookie watcher), [`deploy/cookie-sync.xennick.com.conf`](https://github.com/fishernick/brightspacemcp/blob/master/deploy/cookie-sync.xennick.com.conf) (Reverse proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP access"]
  node_mcpserver["MCP tools<br/>[server.py]"]
  node_inbound["Bearer gate<br/>[server.py]"]
end

subgraph group_lms["Brightspace data"]
  node_auth["Cookie credentials<br/>[auth.py]"]
  node_request["API requester<br/>[server.py]"]
  node_account["Account and courses<br/>[server.py]"]
  node_grades["Grades<br/>[server.py]"]
  node_due["Due items<br/>[server.py]"]
  node_calendar["Calendar events<br/>[server.py]"]
  node_quizzes["Quizzes<br/>[server.py]"]
  node_aggregate["Merged due view<br/>[server.py]"]
  node_content["Course content<br/>[server.py]"]
  node_files["Topic and syllabus files<br/>[server.py]"]
  node_transcription["Video transcription<br/>[server.py]"]
end

subgraph group_sync["Cookie sync"]
  node_extension["Cookie watcher<br/>[background.js]"]
  node_receiver["Cookie receiver"]
  node_env[("Environment file")]
end

node_client(("MCP client"))
node_brightspace["Brightspace LMS"]
node_browser(("Brightspace browser"))
node_service["MCP service"]
node_nginx["Reverse proxy"]

node_client -->|"sends MCP requests"| node_inbound
node_inbound -->|"authorizes"| node_mcpserver
node_mcpserver -->|"uses for LMS calls"| node_request
node_request -->|"loads cookies"| node_auth
node_request -->|"requests API data"| node_brightspace
node_brightspace -->|"returns API data"| node_request
node_account -->|"fetches enrollments"| node_request
node_grades -->|"fetches grades"| node_request
node_due -->|"fetches due feed"| node_request
node_calendar -->|"fetches events"| node_request
node_quizzes -->|"fetches quizzes"| node_request
node_aggregate -->|"fetches source feeds"| node_request
node_content -->|"fetches course TOC"| node_request
node_files -->|"downloads attachments"| node_request
node_transcription -.->|"launches video link"| node_brightspace
node_browser -->|"changes session cookies"| node_extension
node_extension -->|"posts cookies"| node_nginx
node_nginx -->|"forwards request"| node_receiver
node_receiver -->|"updates cookies"| node_env
node_receiver -->|"restarts service"| node_service
node_env -->|"supplies session values"| node_auth

click node_mcpserver "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py"
click node_inbound "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py"
click node_auth "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/auth.py"
click node_request "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py"
click node_account "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py"
click node_grades "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py"
click node_due "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py"
click node_calendar "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py"
click node_quizzes "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py"
click node_aggregate "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py"
click node_content "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py"
click node_files "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py"
click node_transcription "https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py"
click node_extension "https://github.com/fishernick/brightspacemcp/blob/master/extension/background.js"
click node_receiver "https://github.com/fishernick/brightspacemcp/blob/master/cookie_sync_server.py"
click node_service "https://github.com/fishernick/brightspacemcp/blob/master/deploy/brightspace-mcp.service"
click node_nginx "https://github.com/fishernick/brightspacemcp/blob/master/deploy/cookie-sync.xennick.com.conf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcpserver,node_inbound,node_client,node_browser toneBlue
class node_auth,node_request,node_account,node_grades,node_due,node_calendar,node_quizzes,node_aggregate,node_content,node_files,node_transcription toneAmber
class node_extension,node_receiver,node_env toneMint
class node_brightspace toneIndigo
class node_service,node_nginx toneTeal
```

## Components

### MCP access

- [MCP tools](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py): `src/brightspacemcp/server.py`
- [Bearer gate](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py): `src/brightspacemcp/server.py`

### Brightspace data

- [Cookie credentials](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/auth.py): `src/brightspacemcp/auth.py`
- [API requester](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py): `src/brightspacemcp/server.py`
- [Account and courses](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py): `src/brightspacemcp/server.py`
- [Grades](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py): `src/brightspacemcp/server.py`
- [Due items](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py): `src/brightspacemcp/server.py`
- [Calendar events](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py): `src/brightspacemcp/server.py`
- [Quizzes](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py): `src/brightspacemcp/server.py`
- [Merged due view](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py): `src/brightspacemcp/server.py`
- [Course content](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py): `src/brightspacemcp/server.py`
- [Topic and syllabus files](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py): `src/brightspacemcp/server.py`
- [Video transcription](https://github.com/fishernick/brightspacemcp/blob/master/src/brightspacemcp/server.py): `src/brightspacemcp/server.py`

### Cookie sync

- [Cookie watcher](https://github.com/fishernick/brightspacemcp/blob/master/extension/background.js): `extension/background.js`
- [Cookie receiver](https://github.com/fishernick/brightspacemcp/blob/master/cookie_sync_server.py): `cookie_sync_server.py`
- **Environment file**

### Other components

- **MCP client**
- **Brightspace LMS**
- **Brightspace browser**
- [MCP service](https://github.com/fishernick/brightspacemcp/blob/master/deploy/brightspace-mcp.service): `deploy/brightspace-mcp.service`
- [Reverse proxy](https://github.com/fishernick/brightspacemcp/blob/master/deploy/cookie-sync.xennick.com.conf): `deploy/cookie-sync.xennick.com.conf`

## Connections

- MCP client → Bearer gate: sends MCP requests
- Bearer gate → MCP tools: authorizes
- MCP tools → API requester: uses for LMS calls
- API requester → Cookie credentials: loads cookies
- API requester → Brightspace LMS: requests API data
- Brightspace LMS → API requester: returns API data
- Account and courses → API requester: fetches enrollments
- Grades → API requester: fetches grades
- Due items → API requester: fetches due feed
- Calendar events → API requester: fetches events
- Quizzes → API requester: fetches quizzes
- Merged due view → API requester: fetches source feeds
- Course content → API requester: fetches course TOC
- Topic and syllabus files → API requester: downloads attachments
- Video transcription → Brightspace LMS: launches video link
- Brightspace browser → Cookie watcher: changes session cookies
- Cookie watcher → Reverse proxy: posts cookies
- Reverse proxy → Cookie receiver: forwards request
- Cookie receiver → Environment file: updates cookies
- Cookie receiver → MCP service: restarts service
- Environment file → Cookie credentials: supplies session values