Skip to content

MCP Server addition and modification of SimpleChat API to accomodate … #722

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gregunger-microsoft wants to merge 4 commits into
base: Development
Choose a base branch
from
Open

MCP Server addition and modification of SimpleChat API to accomodate … #722

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e913f2f
MCP Server addition and modification of SimpleChat API to accomodate …
gregunger_microsoft Feb 19, 2026
e90427f
non tested checkpoint
gregunger_microsoft Feb 23, 2026
77e1b32
added dynamic tool gating and added tag tool
gregunger_microsoft Feb 26, 2026
dc65180
Multiple bug fixes in mcp server
gregunger_microsoft Feb 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@ STYLE
Always conform to the coding styles defined in styleguide.md in the root of the repo when generating code. If the styleguide.md is missing, try to check the readme.md in the repo root. If readme.md is missing or contains no useful style information, use the default style of the language. If the default style is not defined, follow best practices, accessibility guidelines, and readability.
Use @terminal when answering questions about Git.

MCP TOOL RESPONSE FORMATTING
When displaying results from MCP Server tool calls (e.g. #simplechat-mcp-server-local, #simplechat-mcp-server-cloud), ALWAYS format the response as a readable markdown table. Never show raw JSON output. Extract the most relevant fields and present them in a clean table. For search results, include columns like: #, Name/Title, Score, Key Details. For document lists, include: #, File Name, Classification, Upload Date. For conversations, include: #, Title, Date, Message Count. Adapt columns to fit the data returned. Always show the total count and auth_source at the top.

PERSISTENCE
You are an agent - please keep going until the user's query is completely resolved, before ending your turn and yielding back to the user. Only terminate your turn when you are sure that the problem is solved.

Expand Down
6 changes: 6 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ priv-*
# temporary files
flask_session

# local user workspace
gunger/

# node modules
/node_modules
/package-lock.json
Expand All @@ -42,3 +45,6 @@ flask_session
**/my_chart.png
**/sample_pie.csv
**/sample_stacked_column.csv
application/external_apps/mcp/.env.azure
application/external_apps/mcp/logs/mcp_stderr.log
application/external_apps/mcp/logs/mcp_stdout.log
9 changes: 9 additions & 0 deletions application/external_apps/mcp/.dockerignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
.env
logs/
__pycache__/
*.pyc
*.pyo
*.pyd
.venv/
venv/
.env.*
17 changes: 17 additions & 0 deletions application/external_apps/mcp/Dockerfile
View file
Open in desktop
Copy link
Collaborator

@Bionic711 Bionic711 Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any reason this would not run in a distroless (mcr.microsoft.com/azurelinux/distroless/python:3.12) multi-step build like the core app?

Copy link
Collaborator Author

@gregunger-microsoft gregunger-microsoft Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So no issues if distroless is a requirement. But at this point in the development, it is premature for the MCP Server itself and for non-production use-cases. We could easily have multiple docker files to accomodate distroless and not distroless.

Using a distroless container image means your container includes only your application and its runtime — no shell, no package manager, no debugging tools.

That sounds ideal, especially prematurely when adding new functionality/components to a system that may require higher visibility/observability in a given system.

Here are the main reasons why using a distroless image can be a bad idea:
#1 Debugging Becomes Painful
Distroless images don’t include:
bash / sh
curl
ps
netstat
apt / yum

  • i.e. Most standard Linux tools

If something goes wrong in production, you can’t exec into the container and inspect it. Because there is no shell.

This makes incident response slower and more complex. You need:

  • Sidecar debug containers
  • Ephemeral debug images
  • Rebuilds just to inspect behavior

That’s fine for mature software. Not so great for fast-moving agile software development.

#2 Local Development Becomes Friction-Filled
Distroless is great for production minimalism.
It’s terrible for:

  • Experimentation
  • Rapid troubleshooting
  • Investigating weird runtime edge cases

Developers often end up maintaining:

  • One Dockerfile for dev
  • One for prod

Now you have divergence risk.

#3 Observability Tooling Limitations
Many debugging or monitoring tools assume basic OS utilities exist.
If you rely on:

  • Runtime profilers
  • On-the-fly tracing
  • Crash dump analysis
  • Temporary diagnostics
    You may discover the container simply doesn’t support what you need.

#4 Operational Complexity Increases
Distroless pushes complexity outward.
Instead of “Let’s exec in and look.”
You now need:

  • Debug sidecars
  • Separate debug images
  • Stronger logging discipline
  • More complete telemetry
    If your observability is weak, distroless will expose it brutally.

#5 Compatibility Surprises
Some apps assume:

  • Timezone data exists
  • CA certificates are present
  • Locale data is available
  • /bin/sh exists for subprocesses
    Distroless images may omit or minimally include these.
    You discover issues at runtime.

#6 Security Gains May Be Marginal
Distroless is often sold as “more secure.”
But:

  • The real attack surface is usually your application.
  • Most container exploits rely on runtime vulnerabilities, not bash.
  • A properly hardened minimal distro (e.g., Alpine or slim Debian) may provide nearly identical risk reduction.
    Security benefit is real — but sometimes overstated.

#7 Not Ideal for Dynamic Environments
If your application:

  • Installs plugins dynamically
  • Runs scripts
  • Uses subprocess-heavy workflows
  • Executes user-provided commands
    Distroless can break those assumptions.

Copy link
Collaborator

@Bionic711 Bionic711 Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It will be a requirement for production (a ton of customer have requested it because of the amount of CVEs that are eliminated), but your points are valid for rapid iteration/development. That said, for rapid iteration, you should also be able to run it locally/dev container that has obserability/tools. We also prefer to rely on high and strong logging discipline.

Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

ENV PYTHONUNBUFFERED=1
ENV FASTMCP_HOST=0.0.0.0
ENV FASTMCP_PORT=8000

EXPOSE 8000

CMD ["python", "server_minimal.py"]
117 changes: 117 additions & 0 deletions application/external_apps/mcp/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
# SimpleChat MCP Server (FastMCP)

This MCP server provides **10 active tools** for interacting with SimpleChat via the Model Context Protocol (Streamable HTTP transport).

Copy link

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This README documents the MCP server, but the repo’s main feature docs live under docs/explanation/features/<version>/.... Consider adding a corresponding feature doc there (and linking to this README) so the new external integration is discoverable alongside other SimpleChat features.

Suggested change
For a high-level overview of this integration alongside other SimpleChat features, see the MCP feature documentation under `docs/explanation/features/<version>/MCP_SERVER_INTEGRATION.md`.

Copilot uses AI. Check for mistakes.
## Tools

### Authentication (2 tools)
| Tool | Auth | Description |
|------|------|-------------|
| **login_via_oauth** | None | Starts device-code OAuth login. Returns `user_code` + `verification_uri` for sign-in. |
| **oauth_login_status** | Optional | Returns current login status for both PRM (bearer token) and device-code flows. |

### User Profile (1 tool)
| Tool | Auth | SimpleChat API | Description |
|------|------|----------------|-------------|
| **show_user_profile** | Required | `POST /external/login` | Returns the authenticated user's profile, roles, and all token claims. |

### Conversations & Chat (3 tools)
| Tool | Auth | SimpleChat API | Description |
|------|------|----------------|-------------|
| **list_conversations** | Required | `GET /api/get_conversations` | Returns all conversations for the authenticated user. |
| **get_conversation_messages** | Required | `GET /api/get_messages` | Returns messages for a specific conversation. Params: `conversation_id` (required). |
| **send_personal_chat_message** | Required | `POST /api/chat` | Sends a message scoped to the user's personal workspace and returns AI response. Only personal documents are used for RAG. Params: `message` (required), `conversation_id` (optional — creates new if empty). |

### Personal Workspace (2 tools)
| Tool | Auth | SimpleChat API | Description |
|------|------|----------------|-------------|
| **list_personal_documents** | Required | `GET /api/documents` | Returns paginated personal documents. Params: `page`, `page_size`, `search`, `classification`, `author`, `keywords`. |
| **list_personal_prompts** | Required | `GET /api/prompts` | Returns paginated personal prompts. Params: `page`, `page_size`, `search`. |

### Search (1 tool)
| Tool | Auth | SimpleChat API | Description |
|------|------|----------------|-------------|
| **search_personal_documents** | Required | `POST /api/search` | Hybrid (text + vector) search across the user's personal documents only. Params: `query` (required), `document_id`, `top_n`. |

### Agent Templates (1 tool)
| Tool | Auth | SimpleChat API | Description |
|------|------|----------------|-------------|
| **list_agent_template_tags** | Required | `GET /api/agent-templates/tags` | Returns a deduplicated, sorted list of all tags across approved agent templates. |

### Unapproved Tools (disabled by default)
The following tools are gated behind the `ENABLE_UNAPPROVED_TOOLS` environment variable.
Set `ENABLE_UNAPPROVED_TOOLS=true` to make them available to MCP clients.

- `list_public_workspaces` — `GET /api/public_workspaces`
- `list_group_workspaces` — `GET /api/groups`
- `list_group_documents` — `GET /api/group_documents`
- `list_group_prompts` — `GET /api/group_prompts`
- `list_public_documents` — `GET /api/public_documents`
- `list_public_prompts` — `GET /api/public_prompts`
- `send_chat_message` — `POST /api/chat` (all scopes; approved version is `send_personal_chat_message`)
- `search_documents` — `POST /api/search` (all scopes; approved version is `search_personal_documents`)

## Prerequisites

- SimpleChat running locally (default <https://localhost:5000>)
- Entra bearer token issued for the SimpleChat API (audience `api://<CLIENT_ID>`)
- The token includes the **ExternalApi** role (or equivalent scope)

## Setup

1. Create a `.env` file based on `example.env`.
2. Install dependencies:
- `pip install -r requirements.txt`

## Run

- The MCP server always listens on: `http://localhost:8000/mcp`
- Run locally via script: `.\run_mcp_server.ps1`
- Run locally directly: `python server_minimal.py`

## Environment Variables

### Required — SimpleChat Connection
- `SIMPLECHAT_BASE_URL` — Base URL for SimpleChat (e.g. `https://localhost:5000`)
- `SIMPLECHAT_VERIFY_SSL` — Whether to verify SSL certificates (`true` or `false`)

### Required — MCP Server Configuration
- `MCP_REQUIRE_AUTH` — Enable PRM authentication (`true` or `false`)
- `MCP_PRM_METADATA_PATH` — Path to PRM metadata JSON file (e.g. `prm_metadata.json`)
- `MCP_SESSION_TOKEN_TTL_SECONDS` — TTL in seconds for cached MCP session tokens (e.g. `3600`)
- `FASTMCP_HOST` — Bind host (set by `run_mcp_server.ps1` to `0.0.0.0`)
- `FASTMCP_PORT` — Bind port (set by `run_mcp_server.ps1` to `8000`)
- `FASTMCP_SCHEME` — URL scheme for PRM metadata (`http` for local, `https` for production)

### Required — OAuth / Device-Code Flow
- `OAUTH_AUTHORIZATION_URL` — Entra authorization endpoint
- `OAUTH_TOKEN_URL` — Entra token endpoint
- `OAUTH_DEVICE_CODE_URL` — Entra device-code endpoint (auto-inferred from `OAUTH_TOKEN_URL` if omitted)
- `OAUTH_CLIENT_ID` — App registration client ID
- `OAUTH_CLIENT_SECRET` — App registration client secret (not sent in device-code flow for public clients)
- `OAUTH_SCOPES` — Space-separated scopes (e.g. `api://<CLIENT_ID>/ExternalApi User.Read offline_access openid profile`)
- `OAUTH_TIMEOUT_SECONDS` — Device-code polling timeout in seconds (e.g. `900`)

### Optional
- `ENABLE_UNAPPROVED_TOOLS` — Enable unapproved tools (group/public workspace tools). Default `false`.
- `OAUTH_REDIRECT_PORT` — Redirect port for auth-code flow (default: `53682`)
- `OAUTH_USE_DEVICE_CODE` — Enable device-code flow (`true` or `false`)
- `OAUTH_OPEN_BROWSER` — Auto-open browser during device-code flow (`false` by default)

## OAuth Login Notes

- `login_via_oauth` uses the device-code flow. The tool response includes `user_code` + `verification_uri`, and the server prints a message to stdout.
- Background polling exchanges the device code for an access token, then creates a SimpleChat session via `/external/login`.
- PRM authentication (bearer token from MCP client) is also supported and takes priority over device-code flow.

## PRM (Protected Resource Metadata)

The MCP server serves PRM metadata at:
`http://localhost:8000/.well-known/oauth-protected-resource`

The `prm_metadata.json` file is a structural template. At runtime, `authorization_servers` and `scopes_supported` are dynamically set from `OAUTH_TOKEN_URL` and `OAUTH_CLIENT_ID` environment variables. The `resource` field is set from the request origin. All three values are required — missing env vars cause an immediate startup error.

## Deployment

Use `deploy_mcp_containerapp.ps1` to build and deploy to Azure Container Apps.
The Dockerfile is included for container builds.
Loading