Skip to content

feat: Add MCP manifest for hustcc-mcp-mermaid #235

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

Closed
wants to merge 1 commit into from
Closed

feat: Add MCP manifest for hustcc-mcp-mermaid #235

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
94 changes: 94 additions & 0 deletions mcp-registry/servers/hustcc-mcp-mermaid.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
{
"name": "@mcp/mermaid-server",
"display_name": "MCP Mermaid Server",
Comment on lines +2 to +3
Copy link

@coderabbitai coderabbitai bot Aug 18, 2025

Choose a reason for hiding this comment

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

💡 Verification agent

🧩 Analysis chain

Confirm naming conventions: scoped package in name field

If your registry expects a human-readable server id (often without npm scope) vs. the npm package name, using a scoped npm name in name might be inconsistent with other entries.

Run this to compare with existing manifests:

🏁 Script executed:

#!/bin/bash
# Inspect naming patterns across existing server manifests
fd -a 'mcp-registry/servers/*.json' | xargs -I{} sh -c 'echo "== {} =="; jq -r ".name" "{}"'

Length of output: 96

🏁 Script executed:

#!/bin/bash
# Find all server manifests and print their "name" fields for naming convention comparison
find mcp-registry/servers -maxdepth 1 -type f -name '*.json' | xargs -I{} sh -c 'echo "== {} =="; jq -r ".name" "{}"'

Length of output: 21436

Align scoped package naming for Mermaid server

Most scoped entries use the <packageName>@<scope>.json file name pattern to match "name": "@<scope>/<packageName>". Your manifest is currently:

  • File: mcp-registry/servers/hustcc-mcp-mermaid.json
  • name: "@mcp/mermaid-server"

To conform:

• Rename the manifest file:
from mcp-registry/servers/hustcc-mcp-mermaid.json
to mcp-registry/servers/mermaid-server@mcp.json

This ensures file name and "name" stay in sync.
Alternatively, if you prefer an unscoped server ID, update the "name" to "hustcc-mcp-mermaid" to match the current file.

🤖 Prompt for AI Agents 
In mcp-registry/servers/hustcc-mcp-mermaid.json around lines 2-3, the manifest
"name" field is scoped as "@mcp/mermaid-server" but the file name uses an
unscoped pattern (hustcc-mcp-mermaid.json); fix by making file name and "name"
consistent: either rename the file to
mcp-registry/servers/mermaid-server@mcp.json to match "name":
"@mcp/mermaid-server", or change the "name" value to "hustcc-mcp-mermaid" so it
matches the current file name; pick one option and update the repository
accordingly.

"description": "Generate mermaid diagram and chart with AI MCP dynamically.",
"repository": {
"type": "git",
"url": "https://github.com/hustcc/mcp-mermaid"
},
"author": {
"name": "hustcc",
"email": "i@hust.cc"
},
"license": "MIT",
"categories": [
"Dev Tools",
"Media Creation"
],
"tags": [
"mcp",
"mcp-server",
"mermaid"
],
"arguments": {
"API_KEY": {
"description": "OpenAI API Key.",
"required": true,
"example": "sk-xxx"
},
"BASE_URL": {
"description": "OpenAI API base url. Default: https://api.openai.com/v1.",
"required": false,
"example": "https://api.openai.com/v1"
},
"MODEL": {
"description": "Model name. Default: gpt-4-turbo.",
"required": false,
"example": "gpt-4-turbo"
}
},
"tools": [
{
"name": "Diagram",
"description": "Generate mermaid diagram and chart."
}
],
"resources": [],
"prompts": [],
"installations": {
"uvx": {
"type": "uvx",
"command": "uvx",
"args": [
"@mcp/mermaid-server",
"--port",
"8000"
],
"description": "Run with uvx"
},
Comment on lines +48 to +58
Copy link

@coderabbitai coderabbitai bot Aug 18, 2025

Choose a reason for hiding this comment

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

⚠️ Potential issue

Remove uvx install entry; it won’t execute a Node package

uvx targets Python apps; it can’t run a scoped npm package. Keeping this will mislead users.

Apply this diff to remove the uvx block:

   "installations": {
-    "uvx": {
-      "type": "uvx",
-      "command": "uvx",
-      "args": [
-        "@mcp/mermaid-server",
-        "--port",
-        "8000"
-      ],
-      "description": "Run with uvx"
-    },
🤖 Prompt for AI Agents 
In mcp-registry/servers/hustcc-mcp-mermaid.json around lines 48 to 58, remove
the entire "uvx" installation block (the "uvx" key and its nested object)
because uvx targets Python apps and cannot execute a scoped npm package; after
removing the block, ensure the surrounding JSON remains valid (remove any
now-unnecessary trailing comma or adjust commas between adjacent entries).

"npm": {
"type": "npm",
"command": "npx",
"args": [
"-y",
"@mcp/mermaid-server",
"--port",
"8000"
],
"description": "Run with npx",
"recommended": true
},
Comment on lines +59 to +70
Copy link

@coderabbitai coderabbitai bot Aug 18, 2025

Choose a reason for hiding this comment

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

💡 Verification agent

🧩 Analysis chain

Pass API key via env for npm; verify package name correctness

  • The npm/npx command doesn’t set API_KEY; add an env map so users don’t paste secrets into args.
  • Verify the published npm package name. The repo is “mcp-mermaid”; ensure the package is actually “@mcp/mermaid-server” (or update to the correct one).
     "npm": {
       "type": "npm",
       "command": "npx",
       "args": [
         "-y",
         "@mcp/mermaid-server",
         "--port",
         "8000"
       ],
+      "env": {
+        "API_KEY": "${OPENAI_API_KEY}"
+      },
       "description": "Run with npx",
       "recommended": true
     },

🏁 Script executed:

#!/bin/bash
# Check if other manifests use per-installation env blocks and inspect npm package naming patterns
echo "Search for env blocks under installations:"
rg -n -C2 '"installations"\s*:\s*{(?s).*"env"\s*:'

echo "List npm install commands for comparison:"
rg -n -C2 '"type"\s*:\s*"npm"'

echo "Check for uvx usage elsewhere (should be Python-only):"
rg -n -C2 '"type"\s*:\s*"uvx"'

Length of output: 103242

🌐 Web query:

Is there an npm package published under the name "@mcp/mermaid-server" for the hustcc/mcp-mermaid project?

💡 Result:

There is no npm package published under the name "@mcp/mermaid-server" for the hustcc/mcp-mermaid project as of August 2025.

Supporting details:

  • The official npm package for the hustcc/mcp-mermaid project is named "mcp-mermaid" (not scoped, i.e., no @mcp/ prefix)[8][5]. Installation commands in both the GitHub README and third-party documentation show:

    npm install -g mcp-mermaid

    and configuration instructions reference "mcp-mermaid" in npm and npx commands—not @mcp/mermaid-server[8][5].

  • A search of the npm registry does not return any package named "@mcp/mermaid-server". Several related packages exist, such as:

    • @rtuin/mcp-mermaid-validator: an MCP server for validating Mermaid diagrams[1].
    • @peng-shawn/mermaid-mcp-server: converts Mermaid diagrams to PNG images[6].
    • Packages like mermaid-mcp-server, markdown-mermaid-converter-mcp, and @takanarishimbo/mermaid-live-mcp-server serve similar or related purposes[4][7][10].

  • The official package for hustcc/mcp-mermaid is simply "mcp-mermaid". There is no link between "mcp-mermaid" and any package named "@mcp/mermaid-server" in either the GitHub project or external documentation[8][5][2][3].

Summary table of relevant MCP Mermaid npm packages:

Project / Author Official npm package name Exists on npm as of Aug 2025 Comments
hustcc/mcp-mermaid mcp-mermaid Yes Official, per GitHub and docs[8][5]
— @mcp/mermaid-server No Not published or listed
abekdwight/mermaid-mcp-server mermaid-mcp-server Yes Different author/project[4]
@peng-shawn @peng-shawn/mermaid-mcp-server Yes Similar server, different scope[6]
@rtuin @rtuin/mcp-mermaid-validator Yes Validator-focused[1]
@TakanariShimbo @takanarishimbo/mermaid-live-mcp-server Yes Live rendering-focused[10]

Conclusion:
If you need the official MCP server from hustcc, install the package named "mcp-mermaid", not "@mcp/mermaid-server"[8][5]. There is currently no npm package named "@mcp/mermaid-server", either from hustcc or any other publisher.

Citations:

Correct the NPM package name in hustcc-mcp-mermaid manifest

The current installation refers to @mcp/mermaid-server, which doesn’t exist. The official package for the hustcc/mcp-mermaid project is published as mcp-mermaid. There is no need for an env block—this server doesn’t require an API key.

Please apply the following diff:

 mcp-registry/servers/hustcc-mcp-mermaid.json
@@ Lines 59-70
-    "npm": {
-      "type": "npm",
-      "command": "npx",
-      "args": [
-        "-y",
-        "@mcp/mermaid-server",
-        "--port",
-        "8000"
-      ],
-      "description": "Run with npx",
-      "recommended": true
-    },
+    "npm": {
+      "type": "npm",
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-mermaid",
+        "--port",
+        "8000"
+      ],
+      "description": "Run with npx",
+      "recommended": true
+    },
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
"npm": {
"type": "npm",
"command": "npx",
"args": [
"-y",
"@mcp/mermaid-server",
"--port",
"8000"
],
"description": "Run with npx",
"recommended": true
},
"npm": {
"type": "npm",
"command": "npx",
"args": [
"-y",
"mcp-mermaid",
"--port",
"8000"
],
"description": "Run with npx",
"recommended": true
},
🤖 Prompt for AI Agents 
In mcp-registry/servers/hustcc-mcp-mermaid.json around lines 59 to 70, the
manifest incorrectly references the non-existent package "@mcp/mermaid-server"
and includes an unnecessary env block; update the npm entry to use the official
package name "mcp-mermaid" (e.g. keep "command": "npx" and set args to ["-y",
"mcp-mermaid", "--port", "8000"]) and remove the env block entirely so the
server runs without an API key.

"docker": {
"type": "docker",
"command": "docker",
"args": [
"run",
"-p",
"8000:8000",
"-e",
"API_KEY=sk-xxx",
"hustcc/mcp-mermaid-server:latest"
],
"description": "Run with docker"
}
Comment on lines +71 to +83
Copy link

@coderabbitai coderabbitai bot Aug 18, 2025

Choose a reason for hiding this comment

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

💡 Verification agent

🛠️ Refactor suggestion

🧩 Analysis chain

Safer Docker example: avoid inline secrets; add --rm

Use the host env var and auto-remove the container when it exits.

     "docker": {
       "type": "docker",
       "command": "docker",
       "args": [
         "run",
+        "--rm",
         "-p",
         "8000:8000",
         "-e",
-        "API_KEY=sk-xxx",
-        "hustcc/mcp-mermaid-server:latest"
+        "API_KEY=${OPENAI_API_KEY}",
+        "hustcc/mcp-mermaid-server:latest"
       ],
       "description": "Run with docker"
     }

🌐 Web query:

Does a Docker image named "hustcc/mcp-mermaid-server" exist (Docker Hub or GHCR), and is port 8000 the correct default expose/port for the server?

💡 Result:

Short answer

  • I could not find any Docker image published as exactly "hustcc/mcp-mermaid-server" on Docker Hub or on GitHub Packages / GHCR. (The GitHub repository exists, but it shows "Packages 0" — i.e. no published container packages.) (github.com)
  • The server's documented default HTTP/SSE port is 3033 (not 8000). The README and server docs state the default port is 3033 for SSE/streamable transport (CLI option --port / -p defaults to 3033). (github.com, glama.ai)

Notes and next steps

  • The repo is hustcc/mcp-mermaid (source + a Dockerfile is in the repo), so you can build a Docker image yourself from that Dockerfile and expose whichever port you want (the server itself defaults to 3033). (github.com)
  • If you want, I can:
    • show the exact docker build / docker run commands to create and run an image that exposes port 3033 (or map it to host port 8000), or
    • search again for similarly named third‑party images (in case someone published a community image under a different registry/name). Which would you prefer?

Citations:

Safer & Correct Docker example: avoid inline secrets, add --rm, correct default port (3033) & local build

You'll need to build the image locally from the hustcc/mcp-mermaid Dockerfile since there’s no published hustcc/mcp-mermaid-server image. The server defaults to port 3033.

   "docker": {
     "type": "docker",
     "command": "docker",
     "args": [
       "run",
+      "--rm",
+      "-p", "3033:3033",
       "-e", "API_KEY=${OPENAI_API_KEY}",
-      "hustcc/mcp-mermaid-server:latest"
+      "mcp-mermaid-server:latest"
     ],
-    "description": "Run with docker"
+    "description": "Run with Docker (build the image locally via `docker build -t mcp-mermaid-server:latest .` first)"
   }

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents 
mcp-registry/servers/hustcc-mcp-mermaid.json around lines 71-83: the Docker
example uses an inline secret, the wrong port, and a non-existent published
image; update it to (1) build the image locally from the repository Dockerfile
and reference that local tag, (2) map the correct default port 3033
(host:container 3033:3033), (3) remove inline API key and use a safer mechanism
such as --env-file (or Docker secrets) to pass API_KEY, and (4) add --rm to the
run args so containers are cleaned up after exit. Ensure the command and args
reflect these changes and the description mentions building locally.

},
"examples": [
{
"title": "Flowchart Example",
"description": "An example of generating a flowchart.",
"prompt": "Please draw a flowchart about the process of making a cup of coffee."
}
],
"is_official": false,
"is_archived": false
}
Loading