# learning-hour-mcp

Generate Learning Hour content for Technical Coaches using AI. Create structured practice sessions that help development teams master technical excellence through the 4C Learning Model.

## What is this?

An MCP server that helps Technical Coaches run Learning Hours - structured 60-minute practice sessions where teams improve their coding skills through deliberate practice. It generates session plans, code examples, and can even create interactive Miro boards.

## Who is this for?

- **Technical Coaches** facilitating team learning sessions
- **Team Leads** wanting to improve their team's technical practices
- **Developers** organizing coding dojos or practice sessions

## Installation

### Prerequisites
1. [Claude Desktop](https://claude.ai/download) - Install the desktop app
2. [Anthropic API Key](https://console.anthropic.com/settings/keys) - Sign up and create a key ($5 free credit for new accounts)

### Complete Setup

Choose your preferred editor:

#### Claude Desktop
Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "learning-hour": {
      "command": "npx",
      "args": ["-y", "learning-hour-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-anthropic-key",
        "MIRO_ACCESS_TOKEN": "your-miro-token-optional",
        "GITHUB_TOKEN": "your-github-token-optional"
      }
    }
  }
}
```

**Configuration steps:**
1. Open Claude Desktop settings (cmd/ctrl + ,)
2. Go to "Developer" → "Edit Config"
3. Paste the configuration above
4. Replace `your-anthropic-key` with your actual key
5. Save and restart Claude Desktop

#### VSCode
Add to your VSCode settings.json:

```json
{
  "mcp.servers": {
    "learning-hour": {
      "command": "npx",
      "args": ["-y", "learning-hour-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-anthropic-key",
        "MIRO_ACCESS_TOKEN": "your-miro-token-optional",
        "GITHUB_TOKEN": "your-github-token-optional"
      }
    }
  }
}
```

**Configuration steps:**
1. Install the [MCP VSCode Extension](https://marketplace.visualstudio.com/items?itemName=modelcontextprotocol.mcp)
2. Open settings.json (Cmd/Ctrl+Shift+P → "Preferences: Open Settings (JSON)")
3. Add the configuration above
4. Replace tokens with your actual values
5. Reload VSCode window (Cmd/Ctrl+Shift+P → "Developer: Reload Window")

#### Cursor
Add to your Cursor configuration:

```json
{
  "mcpServers": {
    "learning-hour": {
      "command": "npx",
      "args": ["-y", "learning-hour-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-anthropic-key",
        "MIRO_ACCESS_TOKEN": "your-miro-token-optional",
        "GITHUB_TOKEN": "your-github-token-optional"
      }
    }
  }
}
```

**Configuration steps:**
1. Open Cursor settings (Cmd/Ctrl + ,)
2. Click on "Features" → "Claude" → "Advanced"
3. Add the MCP server configuration
4. Replace tokens with your actual values
5. Restart Cursor

**Required**: Only `ANTHROPIC_API_KEY` is required. The other tokens enable additional features.

## Quick Start

After installation, try this in Claude:

> "Use the learning hour tools to create a session about the Extract Method refactoring"

Claude will generate a complete 60-minute session plan with:
- Opening connection activity
- Concept introduction 
- Hands-on coding exercise
- Reflection and commitment

## Available Tools

### `generate_session`
Generate a complete Learning Hour session plan with activities following the 4C model (Connect, Concept, Concrete, Conclusion).

```json
{
  "topic": "Feature Envy"
}
```

### `generate_code_example`
Create before/after code examples for a specific topic.

```json
{
  "topic": "Extract Method",
  "language": "typescript"
}
```

### `create_miro_board`
Create a new Miro board or add frames to an existing board (requires `MIRO_ACCESS_TOKEN`).

```json
{
  "sessionContent": { /* from generate_session */ },
  "existingBoardId": "optional-board-id"  // If provided, adds frames to existing board
}
```

### `list_miro_boards`
List all Miro boards accessible with your token (requires `MIRO_ACCESS_TOKEN`).

```json
{
  "limit": 50,  // Optional, max 50
  "cursor": "optional-pagination-cursor"
}
```

### `get_miro_board`
Get details about a specific Miro board (requires `MIRO_ACCESS_TOKEN`).

```json
{
  "boardId": "board-id-to-get"
}
```

### `delete_miro_board`
Delete a Miro board (requires `MIRO_ACCESS_TOKEN`). Use with caution!

```json
{
  "boardId": "board-id-to-delete",
  "confirm": true  // Required safety check
}
```

### `analyze_repository`
Find real code examples in GitHub repositories (requires `GITHUB_TOKEN`).

### `analyze_tech_stack`
Analyze a repository's technology stack to create team-specific content (requires `GITHUB_TOKEN`).

## Optional Features

### Enable Miro Board Creation
*Transform your Learning Hour into a visual, interactive workshop board*

Get a Miro token:
- Go to [Miro Apps](https://miro.com/app/settings/apps)
- Create a new app (name it "Learning Hours")
- Copy the access token
- Add as `MIRO_ACCESS_TOKEN` in your config

### Enable Repository Analysis
*Find real code examples from your team's actual codebase*

Create a [GitHub Personal Access Token](https://github.com/settings/tokens/new):
- Name: "Learning Hour MCP"
- Expiration: 90 days (recommended)
- Permissions: `repo` (read access)
- Add as `GITHUB_TOKEN` in your config

## Learn More

- [Diamante Technical Coaching](https://diamantetechcoaching.com/) - [Refactor to Grow Newsletter](https://subscribepage.io/refactor-to-grow)
- [SammanCoaching.org](https://sammancoaching.org/) - Technical coaching resources and Learning Hour guides
- [Learning Hours](https://sammancoaching.org/learning_hours/index.html) - Catalog of Learning Hour topics
- [4C Learning Model](https://sammancoaching.org/society/index.html) - Connect, Concept, Concrete, Conclusion
- [Technical Coaching](https://www.sammancoaching.org/society/technical_coach.html) - Role and practices

## Troubleshooting

**"Tool not found" error**: Make sure you restarted Claude Desktop after adding the configuration.

**"Invalid API key"**: Check that you copied the entire key including any prefixes (sk-ant-...).

**Miro board not creating**: Check that your MIRO_ACCESS_TOKEN is valid and has board creation permissions.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.

## License

MIT