# Office MCP Server

Remote MCP server for Microsoft Graph with delegated OAuth support.

## Quick start

1. Copy `.env.example` to `.env`.
2. Install dependencies with `npm install`.
3. Run `npm run dev`.
4. The MCP endpoint is `http://localhost:3000/mcp`.
5. For a container path, build with `docker build -t office-mcp .`.

## Auth modes

- `AUTH_ENABLED=false`: local development without bearer-token enforcement.
- `AUTH_ENABLED=true` with `GRAPH_TOKEN_MODE=passthrough`: validates bearer tokens and forwards the same user token to Microsoft Graph.
- `AUTH_ENABLED=true` with `GRAPH_TOKEN_MODE=obo`: validates bearer tokens for this MCP resource and exchanges them for a Microsoft Graph delegated token via on-behalf-of flow.

## Notes

- Streamable HTTP is used for the remote MCP transport.
- OAuth Protected Resource Metadata is exposed when auth is enabled.
- File-oriented tools cap direct content extraction at `MAX_FILE_SIZE_BYTES` and default to 5 MB, matching current Work IQ preview guidance for some file operations.
- `/diagnostics/auth` provides a non-secret snapshot of auth and token-mode configuration for setup troubleshooting.
- The local test suite now covers both unauthenticated and authenticated MCP route behavior with a mocked verified bearer token.

## Current tool coverage

- user profile and organization context
- direct reports
- mail list, get, search, draft, reply, and send
- calendar list, get, create, update, delete, and schedule lookup
- OneDrive search, recent items, item metadata, folder children, and folder creation
- SharePoint site search, site lookup, document libraries, lists, and list items
- Teams joined teams, chats, channels, channel messages, and chat messages
- Word document text extraction
- cross-M365 retrieval via Microsoft Graph search

## Additional docs

- [Architecture](./docs/architecture.md)
- [Deployment](./docs/deployment.md)
- [Entra setup](./docs/entra-setup.md)
- [Auth runbook](./docs/auth-runbook.md)
- [Permissions matrix](./docs/permissions-matrix.md)
- [Tool catalog](./docs/tool-catalog.md)
- [Live verification](./docs/live-verification.md)

## Smoke testing

With the server running locally:

```bash
npm run smoke
```

The default smoke tool is `server_get_status`, so local MCP verification works even without Microsoft Graph credentials.

For auth-enabled setup, use `.env.auth.example` as the starting template.

To call a specific tool:

```bash
SMOKE_TOOL=mail_list_messages SMOKE_TOOL_ARGS='{"top":5}' npm run smoke
```

To exercise bearer-protected mode, set `SMOKE_BEARER_TOKEN` in the environment before running the smoke script.

To inspect a token's audience, scopes, tenant, and expiry without sending it anywhere:

```bash
npm run inspect-token -- "<jwt>"
```

## Diagnostics

For setup troubleshooting:

```bash
curl http://localhost:3000/diagnostics/auth
```

This endpoint includes non-secret warnings for common misconfigurations such as:

- auth disabled
- missing resource audience
- incomplete OBO configuration
- wildcard CORS in production-like setups

When auth is enabled, the MCP server also exposes protected resource metadata at:

```bash
curl http://localhost:3000/.well-known/oauth-protected-resource/mcp
```

To quickly inspect all readiness endpoints together:

```bash
npm run live-readiness
```

When `AUTH_ENABLED=false`, the auth metadata endpoints will correctly return `404`.