# Workspace MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI agents read-time access to workspace databases and project management APIs.

Built with **FastMCP**, this service acts as a universal data gateway — allowing any MCP-compatible agent (Claude Desktop, Copilot, custom orchestrators) to introspect, query, and correlate business data without writing integration code.

---

## Architecture & Stack Rationale

### Why MCP + FastMCP?

**Model Context Protocol** is the emerging standard for connecting LLMs to external tools and data. Instead of building one-off function calls or plugin APIs per agent, MCP provides a single, typed interface that any compliant LLM can discover and invoke at runtime.

- **FastMCP** was chosen over raw `mcp` SDK because it eliminates boilerplate: tools are plain Python functions with a decorator — no JSON-RPC wire protocol handling, no manual capability negotiation.
- The **SSE (Server-Sent Events) transport** allows long-lived connections from agents running in browsers, desktop apps, or cloud functions, and is trivially load-balanced behind Knative or any HTTP ingress.

```
┌──────────────────────┐     MCP/SSE      ┌──────────────────────────────┐
│  AI Agent            │ ◄──────────────► │  Workspace MCP Server        │
│  (Claude, Copilot…)  │                  │  ├─ Database Tools (Mongo)   │
└──────────────────────┘                  │  └─ API Tools (REST)         │
                                          └──────────────────────────────┘
```

### Why MongoDB for Workspace Data?

Workspace applications produce semi-structured, schema-flexible data — project documents, task metadata, user activity logs, and configuration records. MongoDB's document model:
- Handles **polymorphic schemas** without migrations (different document types emit different fields).
- Provides **native aggregation pipelines** for reporting and analytics (counts, grouping, windowed stats).
- Supports **text indexes** for full-text search across notes, descriptions, and logs.
- The `analyze_database` tool gives AI agents runtime introspection — they discover collections, field types, and indexes on their own, without hardcoded schemas.

### Why a Dedicated Project Management API Adapter?

The project management REST API tracks tickets, tasks, projects, and users. Rather than exposing raw HTTP to the LLM (security risk + prompt overhead), the server wraps the API with:
- **Managed authentication** — supports both Bearer token and Basic Auth; credentials never leak into the agent conversation.
- **Structured error boundaries** — non-2xx responses are captured and returned as strings, never as raw stack traces.
- **Metadata tools** (`get_metadata`, `get_custom_fields`) that let the agent self-discover valid enum values and custom field IDs — no hardcoding, no "I don't know what statuses exist."

### Why Knative + Kubernetes for Deployment?

Production workloads demand **zero-downtime updates** and **automatic scaling**:

| Requirement | Solution |
|---|---|
| Scale to zero when idle | Knative Serving auto-scales down to 0 replicas |
| Per-environment isolation | Kubernetes Namespace separation |
| Secret rotation | Pre-deployment `kubectl create secret` from CI/CD |
| Canary rollouts | Knative revision traffic splitting |

The `deploy_kn.sh` script handles the full lifecycle: Docker build, image push to private registry, Kubernetes Secret upsert, and Knative Service apply — all in a single idempotent command.

---

## Tools Overview

### Database (MongoDB)

| Tool | Purpose |
|---|---|
| `analyze_database` | Introspect databases, collections, indexes, and inferred schemas |
| `get_sample_documents` | Peek at documents from any collection |
| `get_distinct_values` | Distinct values and frequency for a field |
| `query_documents` | Filtered queries with projection and sort |
| `aggregate_documents` | MongoDB aggregation pipelines |
| `count_documents` | Document count matching a filter |
| `search_documents` | Full-text search across documents |

### Project Management API (REST)

| Tool | Purpose |
|---|---|
| `check_api_connection` | Verify API connectivity and return caller identity |
| `list_projects` | List all accessible projects |
| `search_items` | Query items by structured condition |
| `get_item_detail` | Full detail — linked items, references, comments |
| `get_metadata` | Discover valid priorities, statuses, categories, projects |
| `find_user` | Resolve users by name or email |
| `get_custom_fields` | List custom fields with API IDs |

---

## Quick Start

```bash
pip install -r requirements.txt

cp .env.example .env
# Edit WORKSPACE_MONGO_URI, API_TOKEN, API_SITE_ID

python server.py
```

Server starts on `http://0.0.0.0:8080` with SSE transport. Connect any MCP client to `http://host:8080/sse`.

## Environment Variables

| Variable | Description |
|---|---|
| `WORKSPACE_MONGO_URI` | MongoDB connection string |
| `API_TOKEN` | Project management API token |
| `API_EMAIL` | Email for Basic Auth (omit for Bearer token) |
| `API_BASE_URL` | API instance URL |
| `API_SITE_ID` | Site ID (preferred over auto-resolve) |
| `SERVER_PORT` | HTTP server port (default `8080`) |

## Docker

```bash
docker build -t workspace-mcp .
docker run -p 8080:8080 --env-file .env workspace-mcp
```

## Deployment

```bash
export AGENT_NAME=workspace-mcp
export DEPLOYMENT_CONTEXT=workspace
bash deploy.sh
```

Requires: Docker, kubectl (with Knative Serving installed), access to a container registry, and a `.env.workspace` file with deployment-specific variables (registry, namespace, pull secret, credentials).