mcp-ms-todo-server by yamonco - MCP Server

License & Open Source Notice

This project is released under the MIT License by our organization. You are free to use, modify, distribute, and use it commercially. See the LICENSE file for details.

MCP-MS-TODO-SERVER (2025 Latest MCP Structure)

This is an API server that integrates Microsoft To Do (Graph API) with MCP (Microsoft Cloud Platform). It is a FastAPI-based MCP server, and all features are provided via a single JSON-RPC endpoint (/mcp) using the tool system. You can quickly deploy and operate in a Docker environment, supporting Streamable HTTP (SSE), REST, and PowerShell (Microsoft.Graph) execution.

Project Structure

- **Microsoft To Do (Graph API) Integration**: Supports authentication and CRUD operations
- **Streamable HTTP (SSE)**: Real-time progress log streaming
- **REST/PowerShell Execution**: REST by default, optional PowerShell (Microsoft.Graph)
- **Docker-based Deployment**: .env configuration, persistent token/log volumes

---

```bash
python -m app.cli users add \
    "time_zone": "Asia/Seoul"

# MCP-MS-TODO-SERVER (2025 Edition)

**A modern, production-grade MCP server for Microsoft To Do, built with FastAPI, Docker, and a strict argument-only automation flow.**

---

## Overview

This project provides a robust, secure, and extensible MCP (Model Context Protocol) server that integrates Microsoft To Do (via Microsoft Graph API) with a clean, tool-based JSON-RPC 2.0 interface. All automation, onboarding, and helper flows are strictly argument-based—**no environment variable dependencies**—for maximum portability, security, and CI/CD compatibility.

**Key Features:**
- Single `/mcp` JSON-RPC endpoint for all features (tools/list, tools/call)
- Microsoft To Do (Graph API) integration: CRUD, list, sync, etc.
- Argument-only CLI and onboarding: no env required, all helpers take explicit arguments
- Secure DB token storage, API key management, RBAC
- Docker-native, production-ready, with Makefile automation
- Real-time streaming (SSE), REST, and optional PowerShell execution
- Clean architecture: domain/usecases/infrastructure separation

---

## Project Structure

mcp-ms-todo-server/ ├── Dockerfile, docker-compose.yml # Containerization & orchestration ├── README.md # This file ├── app/ # Main server code (main.py, tools.py, domain/, usecases/, infrastructure/) ├── auth-helper/ # CLI helper for app registration, onboarding, token import (argument-only) ├── secrets/ # Private tokens, DB, never committed ├── tools/ # JSON schemas for tool definitions ├── tests/, docs/ # Test scripts, Docusaurus docs


---

## Quick Start (Argument-Only, No Env)

1. **Build & Start (Docker):**
   ```bash
   docker compose build
   docker compose up -d

Onboard & Register App (Argument-Only):

python auth-helper/auth-helper.py register-app --mcp-url http://localhost:8081 --master-key <API_KEY> --admin-tenant-id <TENANT_ID> --admin-client-id <ADMIN_CLIENT_ID> --admin-client-secret <ADMIN_CLIENT_SECRET> --profile admin

Import user token (from stdin):

echo '{"access_token":"..."}' | python -m app.cli profiles import --profile alice --from-stdin

Add user API key:

python -m app.cli users add --user-id alice --name "Alice" --template lite --token-profile alice

Run the Server:

make dev-serve
# Or for production
make prod-up

Call Tools (JSON-RPC):

List tools:

{ "method": "tools/list", "params": {} }

Call a tool:

{ "method": "tools/call", "params": { "name": "todo.tasks.get", "arguments": { "list_id": "<LIST_ID>" } } }

Security & Best Practices

No environment variables required for any helper, onboarding, or CLI flow. All secrets and config are passed as arguments.
All tokens, API keys, and secrets are stored in the DB (secrets/), never committed.
API access is protected by API keys (passed via X-API-Key header).
RBAC and tool-level access control are enforced.
.env and secrets/ are gitignored by default.

Main API Usage Examples

Get Task List

{
  "method": "tools/call",
  "params": {
    "name": "todo.tasks.get",
    "arguments": {
      "list_id": "<LIST_ID>"
    }
  }
}

Create Task

{
  "tool": "todo.create_task",
  "params": {
    "list_id": "<LIST_ID>",
    "title": "Prepare meeting",
    "body": "Agenda summary",
    "due": "2025-09-05T09:00:00",
    "time_zone": "Asia/Seoul"
  }
}

Supported Tools (as of 2025)

todo.lists.get: List all To Do lists
todo.lists.mutate: Create, delete, or rename a list
todo.tasks.get: List all tasks in a list
todo.tasks.create: Create a new task
todo.tasks.delete: Delete a task

See /tools/ for full JSON schemas and up-to-date tool definitions.

Advanced: App Registration & Onboarding (No Env, Argument-Only)

All onboarding, app registration, and token import flows are argument-only. Example:

python auth-helper/auth-helper.py register-app \
  --mcp-url http://localhost:8081 \
  --master-key <API_KEY> \
  --admin-tenant-id <TENANT_ID> \
  --admin-client-id <ADMIN_CLIENT_ID> \
  --admin-client-secret <ADMIN_CLIENT_SECRET> \
  --profile admin

Tokens can be imported from stdin or file, and all meta is upserted to the DB via the MCP API.

Security Notes

All secrets, tokens, and API keys are stored in the DB and never committed.
.env, secrets/, and any DB files must be gitignored and kept private.
Only delegated permissions are supported for Microsoft To Do (no application permissions).
Periodic re-login may be required depending on your organization's security policy.

Development & Contribution

See app/ for main server logic and tool definitions
See auth-helper/ for argument-only onboarding and app registration helpers
See tools/ for JSON schemas and tool documentation
See tests/ for smoke tests and usage examples
See docs/ for Docusaurus-based documentation

License

MIT License. See LICENSE file for details.

Contact & Feedback

For questions, issues, or feedback, please open an issue in this repository.

ADMIN_TENANT_ID, ADMIN_CLIENT_ID, ADMIN_CLIENT_SECRET: Graph 앱 등록을 위한 관리자 앱 설정 (Application.ReadWrite.All 필요)