Add MCP servlet endpoints with unit tests #403

Copilot · 2025-11-23T10:07:37Z

Implements JSON API endpoints for MCP (Model Context Protocol) to enable AI agents to validate, render, and analyze PlantUML diagrams. Adds comprehensive unit test coverage.

Changes

Modified `McpServlet.java`

/mcp/check - Validates PlantUML source syntax
- Returns {ok: boolean, errors: [{line, message}]}
- Uses NullOutputStream to avoid generating image data during validation
/mcp/render - Changed response format
- Now returns {ok: boolean, format: string, dataBase64: string}
- Previously returned {status, dataUrl, renderTimeMs, sha256}
/mcp/metadata - Extracts diagram structure
- Parses participants from arrows and declarations
- Detects diagram type (sequence, class, state, usecase)
- Defensive string parsing to prevent IndexOutOfBoundsException
/mcp/workspace/put - Added as alias to /workspace/update
JSON error handling - Catches JsonSyntaxException and returns 400 status

Created `McpServletTest.java`

Six unit tests covering all new endpoints:

Syntax validation (valid and invalid diagrams)
Base64 PNG rendering
Metadata extraction
Workspace lifecycle (create → put → render)
Invalid JSON handling

Tests use WebappTestCase framework for integration testing against embedded Jetty server.

Example Usage

# Validate syntax
curl -X POST http://localhost:8080/mcp/check \
  -H "Content-Type: application/json" \
  -d '{"source": "@startuml\nAlice -> Bob\n@enduml"}'
# → {"ok":true,"errors":[]}

# Render to Base64 PNG
curl -X POST http://localhost:8080/mcp/render \
  -H "Content-Type: application/json" \
  -d '{"source": "@startuml\nAlice -> Bob\n@enduml"}'
# → {"ok":true,"format":"png","dataBase64":"iVBORw0KGgo..."}

# Extract metadata
curl -X POST http://localhost:8080/mcp/metadata \
  -H "Content-Type: application/json" \
  -d '{"source": "@startuml\nAlice -> Bob\n@enduml"}'
# → {"participants":["Alice","Bob"],"diagramType":"sequence","directives":[],"warnings":[]}

Notes

MCP endpoints require PLANTUML_MCP_ENABLED=true environment variable
Workspace endpoints use existing sessionId+diagramId model
All existing endpoints and tests remain unchanged

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

ads.mozilla.org
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 20207 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:20207/,http://[::1]:20207/ -no-remote -profile /tmp/rust_mozprofileksX27z (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 28015 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:28015/,http://[::1]:28015/ -no-remote -profile /tmp/rust_mozprofilembHTFc (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 21156 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:21156/,http://[::1]:21156/ -no-remote -profile /tmp/rust_mozprofileoJgHNm (dns block)
detectportal.firefox.com
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 20207 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:20207/,http://[::1]:20207/ -no-remote -profile /tmp/rust_mozprofileksX27z (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 28015 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:28015/,http://[::1]:28015/ -no-remote -profile /tmp/rust_mozprofilembHTFc (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 21156 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:21156/,http://[::1]:21156/ -no-remote -profile /tmp/rust_mozprofileoJgHNm (dns block)
firefox.settings.services.mozilla.com
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 20207 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:20207/,http://[::1]:20207/ -no-remote -profile /tmp/rust_mozprofileksX27z (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 28015 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:28015/,http://[::1]:28015/ -no-remote -profile /tmp/rust_mozprofilembHTFc (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 21156 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:21156/,http://[::1]:21156/ -no-remote -profile /tmp/rust_mozprofileoJgHNm (dns block)
incoming.telemetry.mozilla.org
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 20207 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:20207/,http://[::1]:20207/ -no-remote -profile /tmp/rust_mozprofileksX27z (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 28015 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:28015/,http://[::1]:28015/ -no-remote -profile /tmp/rust_mozprofilembHTFc (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 21156 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:21156/,http://[::1]:21156/ -no-remote -profile /tmp/rust_mozprofileoJgHNm (dns block)
plantuml.com
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 20207 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:20207/,http://[::1]:20207/ -no-remote -profile /tmp/rust_mozprofileksX27z (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 28015 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:28015/,http://[::1]:28015/ -no-remote -profile /tmp/rust_mozprofilembHTFc (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 21156 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:21156/,http://[::1]:21156/ -no-remote -profile /tmp/rust_mozprofileoJgHNm (dns block)
prod.ohttp-gateway.prod.webservices.mozgcp.net
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 20207 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:20207/,http://[::1]:20207/ -no-remote -profile /tmp/rust_mozprofileksX27z (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 28015 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:28015/,http://[::1]:28015/ -no-remote -profile /tmp/rust_mozprofilembHTFc (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 21156 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:21156/,http://[::1]:21156/ -no-remote -profile /tmp/rust_mozprofileoJgHNm (dns block)
spocs.getpocket.com
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 20207 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:20207/,http://[::1]:20207/ -no-remote -profile /tmp/rust_mozprofileksX27z (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 28015 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:28015/,http://[::1]:28015/ -no-remote -profile /tmp/rust_mozprofilembHTFc (dns block)
- Triggering command: /usr/lib/firefox/firefox /usr/lib/firefox/firefox --marionette --headless --remote-debugging-port 21156 --remote-allow-hosts localhost --remote-allow-origins REDACTED,http://localhost:21156/,http://[::1]:21156/ -no-remote -profile /tmp/rust_mozprofileoJgHNm (dns block)
www.eclipse.org
- Triggering command: /opt/hostedtoolcache/CodeQL/2.23.3/x64/codeql/tools/linux64/java/bin/java /opt/hostedtoolcache/CodeQL/2.23.3/x64/codeql/tools/linux64/java/bin/java -jar /opt/hostedtoolcache/CodeQL/2.23.3/x64/codeql/xml/tools/xml-extractor.jar --fileList=/home/REDACTED/work/plantuml-server/.codeql-scratch/dbs/java/working/files-to-index6979022589543905351.list --sourceArchiveDir=/home/REDACTED/work/plantuml-server/.codeql-scratch/dbs/java/src --outputDir=/home/REDACTED/work/plantuml-server/.codeql-scratch/dbs/java/trap/java (dns block)
www.puppycrawl.com
- Triggering command: /opt/hostedtoolcache/CodeQL/2.23.3/x64/codeql/tools/linux64/java/bin/java /opt/hostedtoolcache/CodeQL/2.23.3/x64/codeql/tools/linux64/java/bin/java -jar /opt/hostedtoolcache/CodeQL/2.23.3/x64/codeql/xml/tools/xml-extractor.jar --fileList=/home/REDACTED/work/plantuml-server/.codeql-scratch/dbs/java/working/files-to-index6979022589543905351.list --sourceArchiveDir=/home/REDACTED/work/plantuml-server/.codeql-scratch/dbs/java/src --outputDir=/home/REDACTED/work/plantuml-server/.codeql-scratch/dbs/java/trap/java (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

This section details on the original issue you should resolve

<issue_title>Add a new MCP Servlet (/mcp/*) with unit tests — target branch mcp1</issue_title>
<issue_description>

Summary

We would like to introduce a new MCP (Model Context Protocol) servlet inside plantuml-server, exposing a structured HTTP/JSON API under /mcp/*.
This API will be consumed by AI assistants (e.g., GitHub Copilot, ChatGPT, Claude, IDE integrations) to validate, analyse, and render PlantUML diagrams in a safe and structured way.

👉 Important: all development for this feature must target the dedicated branch: mcp1.

The goal of this issue is to define the minimal MCP feature set and especially provide unit tests so that Copilot can implement the servlet safely and consistently.

Goals

The MCP servlet must:

Provide predictable, JSON-only endpoints.
Never bypass existing PlantUML security rules.
Be fully isolated from the existing rendering servlets.
Offer a minimal but useful toolset for MCP clients:
- syntax checking,
- rendering,
- diagram metadata extraction,
- ephemeral workspace concept.

Endpoints (initial version)

1. POST `/mcp/check`

Validates a PlantUML source.

Request

{
  "source": "@startuml\nAlice -> Bob: Hello\n@enduml"
}

Response

{
  "ok": true,
  "errors": []
}

If errors occur:

{
  "ok": false,
  "errors": [
    { "line": 2, "message": "Syntax error XYZ" }
  ]
}

2. POST `/mcp/render`

Renders a diagram and returns a PNG encoded as Base64.

Request

{
  "source": "@startuml\nAlice -> Bob\n@enduml"
}

Response

{
  "ok": true,
  "format": "png",
  "dataBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Errors must follow the same structure as /mcp/check.

3. POST `/mcp/metadata`

Returns structural metadata extracted from a diagram (participants, classes, relationships, etc.).

Response example

{
  "participants": ["Alice", "Bob"],
  "directives": ["skinparam ..."],
  "diagramType": "sequence",
  "warnings": []
}

4. POST `/mcp/workspace/create`

Creates a new ephemeral workspace (in-memory only).

Response

{
  "workspaceId": "w-8f1b0341"
}

5. POST `/mcp/workspace/put`

Adds or updates a file in the workspace.

Request

{
  "workspaceId": "w-8f1b0341",
  "filename": "test.puml",
  "content": "..."
}

6. POST `/mcp/workspace/render`

Renders a file stored in the workspace.

Implementation Notes

Create a new dedicated servlet:
net.sourceforge.plantuml.server.servlet.McpServlet
URL mapping: /mcp/*
Only accept POST requests with JSON bodies.
Enforce all PlantUML security profiles and limits.
Workspaces must be stored in a thread-safe in-memory map.

✔️ Unit Tests (JUnit 5)

These are essential for Copilot to generate correct code.

All tests must be placed in:

src/test/java/net/sourceforge/plantuml/server/servlet/McpServletTest.java

### 1. Test: check endpoint accepts valid diagram

@Test
void checkEndpointShouldReturnOkForValidDiagram() throws Exception {
    String json = "{ \"source\": \"@startuml\nAlice -> Bob\n@enduml\" }";

    MockHttpServletRequest req = postJson("/mcp/check", json);
    MockHttpServletResponse resp = new MockHttpServletResponse();

    servlet.service(req, resp);

    assertEquals(200, resp.getStatus());
    String body = resp.getContentAsString();

    assertTrue(body.contains("\"ok\":true"));
    assertTrue(body.contains("\"errors\":[]"));
}

2. Test: check endpoint should report syntax errors

@Test
void checkEndpointShouldReportErrors() throws Exception {
    String json = "{ \"source\": \"@startuml\nThis is wrong\n@enduml\" }";

    MockHttpServletResponse resp = call("/mcp/check", json);

    assertTrue(resp.getContentAsString().contains("\"ok\":false"));
    assertTrue(resp.getContentAsString().contains("errors"));
}

3. Test: render endpoint returns Base64 PNG

@Test
void renderEndpointReturnsPngBase64() throws Exception {
    String json = "{ \"source\": \"@startuml\nAlice -> Bob\n@enduml\" }";

    MockHttpServletResponse resp = call("/mcp/render", json);

    assertTrue(resp.getContentAsString().contains("\"format\":\"png\""));
    assertTrue(resp.getContentAsString().contains("\"dataBase64\""));
}

4. Test: metadata endpoint returns participants

@Test
void metadataEndpointReturnsParticipants() throws Exception {
    String json = "{ \"source\": \"@startuml\nAlice -> Bob\n@enduml\" }";

    MockHttpServletResponse resp = call("/mcp/metadata", json);

    assertTrue(resp.getContentAsString().contains("Alice"));
    assertTrue(resp.getContentAsString().contains("Bob"));
}

5. Test: workspace lifecycle

@Test
void workspace...

</details>

- Fixes plantuml/plantuml-server#402

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/plantuml/plantuml-server/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

- Modified McpServlet to include required endpoints: - /mcp/check - validates PlantUML source - /mcp/render - renders with dataBase64 response - /mcp/metadata - extracts diagram metadata - /mcp/workspace/put - alias for workspace/update - Created McpServletTest.java with all required unit tests - All tests pass successfully Co-authored-by: arnaudroques <[email protected]>

- Use NullOutputStream for check endpoint to avoid generating image data - Fix array access in metadata extraction to prevent IndexOutOfBoundsException - Add defensive checks for split operations Co-authored-by: arnaudroques <[email protected]>

Initial plan

f69a42d

Copilot AI assigned Copilot and arnaudroques Nov 23, 2025

Copilot started work on behalf of arnaudroques November 23, 2025 10:08 View session

Copilot AI and others added 2 commits November 23, 2025 10:20

Address code review feedback

e6c4c7c

- Use NullOutputStream for check endpoint to avoid generating image data - Fix array access in metadata extraction to prevent IndexOutOfBoundsException - Add defensive checks for split operations Co-authored-by: arnaudroques <[email protected]>

Copilot AI changed the title ~~[WIP] Add new MCP servlet with unit tests~~ Add MCP servlet endpoints with unit tests Nov 23, 2025

Copilot AI requested a review from arnaudroques November 23, 2025 10:28

Copilot finished work on behalf of arnaudroques November 23, 2025 10:28

arnaudroques approved these changes Nov 23, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add MCP servlet endpoints with unit tests #403

Add MCP servlet endpoints with unit tests #403

Uh oh!

Copilot AI commented Nov 23, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Add MCP servlet endpoints with unit tests #403

Are you sure you want to change the base?

Add MCP servlet endpoints with unit tests #403

Uh oh!

Conversation

Copilot AI commented Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Modified McpServlet.java

Created McpServletTest.java

Example Usage

Notes

I tried to connect to the following addresses, but was blocked by firewall rules:

Summary

Goals

Endpoints (initial version)

1. POST /mcp/check

Request

Response

2. POST /mcp/render

Request

Response

3. POST /mcp/metadata

Response example

4. POST /mcp/workspace/create

Response

5. POST /mcp/workspace/put

Request

6. POST /mcp/workspace/render

Implementation Notes

✔️ Unit Tests (JUnit 5)

### 1. Test: check endpoint accepts valid diagram

2. Test: check endpoint should report syntax errors

3. Test: render endpoint returns Base64 PNG

4. Test: metadata endpoint returns participants

5. Test: workspace lifecycle

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Nov 23, 2025 •

edited

Loading

Modified `McpServlet.java`

Created `McpServletTest.java`

1. POST `/mcp/check`

2. POST `/mcp/render`

3. POST `/mcp/metadata`

4. POST `/mcp/workspace/create`

5. POST `/mcp/workspace/put`

6. POST `/mcp/workspace/render`