convez.ai
MCP ServerIntegração & APIsAvançado
nitsuah

Blackboard Learn MCP Server

nitsuah/bb-mcp

API do Blackboard Learn para LLMs via MCP com autenticação e RBAC

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP standalone que expõe a API REST do Blackboard Learn para clientes LLM via HTTP ou stdio, com camada de autenticação OAuth2 e RBAC. Integração pronta para plataformas educacionais, permitindo acesso estruturado a cursos, notas, tarefas e anúncios.

Instalação

$npx convez-ai nitsuah/bb-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 1 dia
Versão
—
Issues abertas
0
Contribuidores
3

Casos de uso

  • Integrar Blackboard Learn com Claude, Cursor ou agentes IA
  • Automatizar consultas de notas, tarefas e anúncios via LLM
  • Construir assistentes educacionais com acesso controlado por papel (RBAC)

Veredito

Solução bem arquitetada e production-ready com 91% cobertura de testes, zero vulnerabilidades críticas e CI/CD robusto. Ideal para instituições que precisam conectar Blackboard Learn a agentes de IA mantendo segurança e conformidade FERPA.

README

A tradução para o português deste README ainda está na fila.

blackboard-learn-mcp

Deploy Status CI Coverage High/Critical Vulns Lint

A standalone Model Context Protocol server wrapping the Blackboard Learn REST API. Point any MCP-compatible client at it — Claude Desktop, Cursor, agent-board, or anything else — and get structured access to courses, grades, assignments, announcements, and more.


Why standalone?

The integration logic lives here, not in the client. Tools like agent-board, Claude Desktop, and Cursor all connect the same way. Build it once, use it everywhere. Blackboard's own team could point internal tooling at this server without touching any frontend code.


Architecture

┌─────────────────────────────────────────────────┐
│   Any MCP Client                                 │
│   (Claude Desktop · Cursor · agent-board · ...)  │
└──────────────────────┬──────────────────────────┘
                       │ MCP Protocol (HTTP or stdio)
                       ▼
┌─────────────────────────────────────────────────┐
│   blackboard-learn-mcp  (this repo)              │
│                                                  │
│   Auth layer       → OAuth2, role gate, FERPA    │
│   Tools (11)       → student + instructor tools  │
│   Metrics          → Prometheus /metrics         │
│   Audit log        → structured JSON → stdout    │
└──────────────────────┬──────────────────────────┘
                       │ REST API
                       ▼
              Blackboard Learn
          (your instance or sandbox)

Quick start

cp .env.example .env   # Fill in BB_CLIENT_ID, BB_CLIENT_SECRET, BB_BASE_URL
docker compose -f config/docker-compose.yml up -d

Development

All checks run via Docker — no local Node.js required.

# Run all tests (79 tests, TypeScript)
docker compose -f config/docker-compose.yml --profile test run --rm test

# Full quality gate: lint + coverage + audit + complexity
make docker-test

# Individual targets
make docker-lint    # lint only
make docker-build   # production image

Pre-commit hooks (type-check on commit, tests on push):

pip install pre-commit && pre-commit install && pre-commit install --hook-type pre-push

See .github/workflows/ci.yml for the full CI pipeline.

Makefile reference

make docker-up        # Build and start the standalone bb-mcp container
make docker-logs      # Follow container logs
make docker-doctor    # Safe env readiness report from inside the container
make docker-probe     # Validate Blackboard credentials + minimal API call
make docker-manifest  # Print the provider manifest from the built image
make docker-tools     # Print the published tool catalog from the built image
make docker-down      # Stop the standalone stack

Docker (recommended)

cp .env.example .env
# Fill in BB_CLIENT_ID, BB_CLIENT_SECRET, BB_BASE_URL
docker compose -f config/docker-compose.yml up -d

Repo-local standalone commands:

make docker-up        # Build and start the standalone bb-mcp container
make docker-logs      # Follow container logs
make docker-doctor    # Safe env readiness report from inside the container
make docker-probe     # Validate Blackboard credentials + minimal API call
make docker-manifest  # Print the provider manifest from the built image
make docker-tools     # Print the published tool catalog from the built image
make docker-down      # Stop the standalone stack

The standalone compose stack keeps the same Dockerfile path used by agent-board, but now adds a more confined runtime posture: read-only filesystem, dropped Linux capabilities, no-new-privileges, and a small /tmp tmpfs for Node runtime needs.

Server is live at http://localhost:3100.

EndpointDescription
POST /mcpMCP protocol entry point
GET /healthLiveness probe
GET /metricsPrometheus text format
GET /manifestProvider contract with capabilities and tool manifest
GET /oauth/authorizeStart the OAuth Authorization Code flow
GET /oauth/callbackComplete OAuth code exchange and return a managed session
GET /sse/search-course-materialsDedicated SSE stream for incremental search_course_materials output
cp .env.example .env
npm install
npm run dev        # tsx watch — hot reload

stdio mode (Claude Desktop / Cursor)

npm run build
node dist/index.js --stdio

CLI inspection commands

# Show available runtime modes and inspection commands
node dist/index.js --help

# Print the provider manifest without starting the server
node dist/index.js --manifest

# List the published tools with role coverage
node dist/index.js --tools

# Emit a safe environment readiness report (no secrets printed)
node dist/index.js --doctor

# Validate Blackboard credentials and a minimal API call
node dist/index.js --probe

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "blackboard-learn": {
      "command": "node",
      "args": ["/path/to/bb-mcp/dist/index.js", "--stdio"]
    }
  }
}

Configuration

Copy .env.example to .env and set:

VariableRequiredDescription
BB_CLIENT_ID✅OAuth2 app client ID from developer.blackboard.com
BB_CLIENT_SECRET✅OAuth2 app client secret
BB_BASE_URL✅Base URL of your Blackboard Learn instance
BB_OAUTH_REDIRECT_URI—Override the OAuth callback URL (defaults to PUBLIC_BASE_URL + /oauth/callback)
BB_OAUTH_SCOPE—Optional scope string for the authorization code flow
BB_OAUTH_AUTHORIZATION_PATH—Override Blackboard authorization endpoint path
BB_OAUTH_TOKEN_PATH—Override Blackboard token endpoint path
PORT—HTTP port (default 3100)
LOG_LEVEL—info or debug (default info)
METRICS_PUSH_URL—Prometheus push gateway URL (optional)
RESTRICTED_TOOLS—Comma-separated tool names requiring FERPA auth

Getting Blackboard credentials:
Register a REST API application at developer.blackboard.com. Use the free developer sandbox for testing — no live Blackboard instance required.

Authorization Code flow

bb-mcp now supports an operator-driven OAuth Authorization Code flow in addition to the existing client credentials probe path.

  1. Visit GET /oauth/authorize to start the flow.
  2. Blackboard redirects back to GET /oauth/callback.
  3. bb-mcp validates the state, performs PKCE-backed token exchange, and returns a managed session payload.

For non-browser operators, GET /oauth/authorize?format=json returns the authorization URL and redirect URI without issuing an HTTP redirect.


Tools

Every tool requires a caller_identity argument:

{
  "caller_identity": {
    "userId": "bbuser123",
    "role": "student",
    "clientApp": "agent-board"
  }
}

For FERPA-restricted tools, add "ferpa_authorized": true — the calling application is responsible for asserting this only after real identity verification.

Student tools

ToolDescription
get_my_coursesCourses the caller is enrolled in
get_upcoming_assignmentsAssignments due within N days, sorted by due date
get_my_gradesGrade breakdown across all courses or one course
get_course_contentCourse modules and materials, with optional keyword search
get_assignment_feedbackInstructor comments, rubric scores, and annotations
get_announcementsCourse announcements
create_assignment_submissionSubmit an assignment attempt with optional student comments

Instructor tools

ToolDescriptionFERPA required
list_rosterEnrolled users for a course, including user IDs and usernames—
get_gradesCourse-wide or user-scoped grade details, optionally filtered to one column✅
get_submission_statusWho submitted, who hasn't, timestamps✅
get_grade_distributionMean, median, std dev, A/B/C/D/F buckets✅
get_discussion_summaryParticipant count and post excerpts for a thread—
get_at_risk_studentsStudents with low grades or many missing submissions✅
draft_announcementAI-assisted announcement draft, optionally posted—

Shared tools

ToolDescription
search_course_materialsFull-text search across content in one or all courses

MCP Resources

URIDescription
course://{courseId}Full course object as JSON

Identity & access control

The auth layer enforces three things before any Blackboard API call is made:

  1. caller_identity is required on every tool call — the client asserts who is asking
  2. Role gate — instructor-only tools reject role: "student" callers
  3. FERPA gate — tools that access protected student data require ferpa_authorized: true

Every access attempt (granted or denied) is written to stdout as structured JSON:

{
  "timestamp": "2026-03-24T10:00:00.000Z",
  "event": "access.granted",
  "tool": "get_my_grades",
  "userId": "bbuser123",
  "role": "student",
  "courseId": null,
  "clientApp": "agent-board",
  "reason": null
}

This format is suitable for ingestion by any log aggregator (Datadog, CloudWatch, Loki, etc.).


Metrics

GET /metrics returns Prometheus-compatible text:

bb_mcp_tool_calls_total{tool="get_my_courses"} 42
bb_mcp_tool_errors_total{tool="get_my_grades"} 1
bb_mcp_tool_avg_duration_ms{tool="get_upcoming_assignments"} 238

Set METRICS_PUSH_URL to push to a Prometheus push gateway every 60 seconds.


agent-board integration

The server runs as a service in agent-board's Docker stack. The connector config lives at agent-board/config/connectors.json:

{
  "name": "Blackboard Learn",
  "mcp_server": "http://bb-mcp:3100",
  "system_prompt": "You are a helpful study assistant...",
  "safety_config": "strict",
  "guided_prompts": [
    "What do I have due this week?",
    "How am I doing in my courses?",
    "Summarize what I missed"
  ]
}

agent-board proxies MCP calls through POST /api/mcp/blackboard-learn/proxy, keeping credentials server-side.


Project structure

bb-mcp/
├── src/
│   ├── index.ts          Entry point — HTTP + stdio transports
│   ├── config.ts         Env validation
│   ├── bb-client.ts      Blackboard REST API client (OAuth2 auto-refresh)
│   ├── auth.ts           Role gate, FERPA guard, audit logging
│   ├── metrics.ts        Prometheus metrics + withMetrics() wrapper
│   ├── types.ts          Domain types (BbCourse, BbGrade, etc.)
│   └── tools/
│       ├── student.ts    Student-facing tools
│       ├── instructor.ts Instructor-facing tools
│       └── shared.ts     search_course_materials
├── Dockerfile            Multi-stage build (node:22-slim)
├── docker-compose.yml    Standalone stack (port 3100)
├── .env.example
├── package.json
└── tsconfig.json

Sandbox testing

No live Blackboard instance needed. Register a free developer account at developer.blackboard.com, create a REST API application, and use the provided sandbox URL as BB_BASE_URL. The sandbox exposes the full API surface with pre-populated test data.


License

MIT

Community Standards

Shared community policies are centralized in https://github.com/nitsuah/.github:

Ver o original no GitHub

Bom para

Relacionados