# Ed Discussions MCP Server

A comprehensive Model Context Protocol (MCP) server for Ed Discussions (EdStem) platform, enabling AI assistants to interact with course discussions, manage threads, comments, and facilitate Q&A.

## Status

✅ **Functional** - Core MCP server with 16 tools implemented and tested

## Features

### Implemented Tools (16)

#### System Tools
- `ed_health_check` - Check API connectivity and authentication

#### User Tools  
- `ed_get_current_user` - Get authenticated user information

#### Course Tools
- `ed_list_courses` - List all enrolled courses
- `ed_get_course` - Get detailed course information

#### Thread Tools
- `ed_list_threads` - List threads with filtering and sorting
- `ed_get_thread` - Get thread details (with optional mark_as_read control)
- `ed_create_thread` - Create new question/post/announcement
- `ed_update_thread` - Update thread content or settings
- `ed_delete_thread` - Delete a thread
- `ed_mark_thread_read` - Mark a thread as read
- `ed_mark_thread_unread` - Mark a thread as unread

#### Comment Tools
- `ed_list_comments` - List all comments (thread + answer replies) with participant metadata
- `ed_create_comment` - Add comment to thread
- `ed_update_comment` - Update/endorse comment
- `ed_delete_comment` - Remove comment

#### Analytics Tools
- `ed_course_activity_stats` - Generate student-only leaderboards for activity, answers, hearts, questions, and posts

## Setup

### Prerequisites
- Node.js 18+
- Ed Discussions account with API access
- API token from your institution's Ed instance

### Installation

1. **Get your Ed API token:**
   - Log into Ed Discussions
   - Navigate to: https://us.edstem.org/settings/api-tokens
   - Generate a new token

2. **Clone and configure:**
```bash
git clone https://github.com/yourusername/mcp-ed.git
cd mcp-ed
```

3. **Create `.env` file:**
```bash
ED_API_TOKEN=your-token-here
ED_DOMAIN=edstem.org
ED_REGION=us  # or your region (au, uk, etc.)
```

4. **Install and build:**
```bash
npm install
npm run build
```

5. **Test connection:**
```bash
node build/testConnection.js  # Test API connection
node build/testMCPServer.js   # Test MCP server
```

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration (`%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "ed-discussions": {
      "command": "node",
      "args": ["/path/to/mcp-ed/build/index.js"],
      "env": {
        "ED_API_TOKEN": "your-token-here",
        "ED_DOMAIN": "edstem.org",
        "ED_REGION": "us"
      }
    }
  }
}
```

### Standalone Server

```bash
npm start  # Runs the MCP server on stdio
```

### Using the Inspector

```bash
npx @modelcontextprotocol/inspector build/index.js
```

## API Examples

### List courses
```javascript
{
  "name": "ed_list_courses",
  "arguments": {}
}
```

### Get threads from a course
```javascript
{
  "name": "ed_list_threads",
  "arguments": {
    "course_id": "81559",
    "limit": 10,
    "sort": "new",
    "filter": "unread"
  }
}
```

### Get thread without marking as read
```javascript
{
  "name": "ed_get_thread",
  "arguments": {
    "course_id": "81559",
    "thread_id": "6873464",
    "mark_as_read": false  // Prevents marking thread as seen
  }
}
```

### Generate course activity stats
```javascript
{
  "name": "ed_course_activity_stats",
  "arguments": {
    "course_id": "81559",
    "max_entries": 20
  }
}
```

### Create a new thread
```javascript
{
  "name": "ed_create_thread",
  "arguments": {
    "course_id": "81559",
    "type": "question",
    "title": "Help with assignment",
    "content": "I'm having trouble with...",
    "category": "Assignments",
    "is_anonymous": false
  }
}
```

## Development

### Project Structure
```
mcp-ed/
├── src/
│   ├── index.ts           # MCP server implementation
│   ├── edClient.ts        # Ed API client
│   ├── testConnection.ts  # API connection tester
│   └── testMCPServer.ts   # MCP server tester
├── build/                 # Compiled JavaScript
├── .env                   # API credentials (git-ignored)
└── package.json
```

### Scripts
```bash
npm run build       # Compile TypeScript
npm run dev:watch   # Development mode with auto-rebuild
npm run test        # Run tests
npm run lint        # Lint code
npm start          # Run MCP server
```

### Testing
The server includes comprehensive test suites:
- `testConnection.ts` - Tests Ed API connectivity
- `testMCPServer.ts` - Tests all MCP tools

## Architecture

Built on the Model Context Protocol SDK, following the successful patterns from the Canvas LMS MCP implementation:

- **TypeScript** for type safety
- **Axios** for HTTP requests
- **MCP SDK** for protocol implementation
- **Modular design** for easy extension

## Read Status Control

The Ed MCP Server provides fine-grained control over thread read status:

- **Read without marking**: Set `mark_as_read: false` when calling `ed_get_thread`
- **Default behavior**: Threads are marked as read when accessed (preserves normal Ed behavior)
- **Manual control**: Use `ed_mark_thread_read` and `ed_mark_thread_unread` tools
- **Preserves privacy**: Reading threads without marking them prevents others from knowing you've read them

## Security

- API tokens are stored in environment variables
- Never commit `.env` files
- Supports anonymous posting where allowed
- Respects course privacy settings

## Roadmap

### Near-term
- [ ] Add search functionality
- [ ] Implement file upload support
- [ ] Add bulk operations
- [ ] Create notification system

### Long-term
- [ ] WebSocket support for real-time updates
- [ ] Analytics and reporting tools
- [ ] LMS integration features
- [ ] Advanced filtering and sorting

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Test thoroughly
4. Submit a pull request

## Support

- **Issues**: https://github.com/yourusername/mcp-ed/issues
- **Discussions**: Use GitHub Discussions for questions

## License

MIT - See LICENSE file for details

## Acknowledgments

- Built on patterns from [Canvas LMS MCP](https://github.com/DMontgomery40/mcp-canvas-lms)
- Uses the [Model Context Protocol SDK](https://modelcontextprotocol.io)
- Thanks to the Ed Discussions team for API access