使用说明

自动文档机器人

使用 Microsoft 365 Copilot 代理自动创建 Confluence 文档页面。单个MCP服务器（create_confluence_doc）承担一切：生成维基标记，创建页面，通过服务器端美人鱼图 mmdc 将其上传为附件并设置标签。

建筑

User (Teams / M365 Copilot)
    → Copilot Agent (Microsoft Copilot Studio)
    → ngrok Tunnel (Port 8080)
    → nginx Reverse Proxy
        /mermaid/mcp → mcp-mermaid:3000 (create_confluence_doc)
    → Confluence Cloud REST API

代理只发送结构化纯文本数据（以逗号分隔）。服务器从中构建wiki标记，渲染图表并创建页面。

详细流程

flowchart TD
    A[User beschreibt Prozess in Teams] --> B{Agent: Titel + min. 3 Schritte vorhanden?}
    B -->|Nein| C[Agent stellt Rueckfragen]
    C --> A
    B -->|Ja| D["Agent extrahiert: title, summary,<br>prerequisites, steps, mermaid_code, labels"]
    D --> E["Agent ruft create_confluence_doc auf<br>alle Parameter als einfache Strings"]
    E --> F["nginx empfaengt POST /mermaid/mcp<br>leitet weiter an mcp-mermaid:3000"]
    F --> G["MCP-Server: parseList<br>Semikolon-Strings in Arrays"]
    G --> H["buildWikiMarkup<br>h1, info-Panel, Schritte, Voraussetzungen"]
    H --> I["Confluence REST API: POST /rest/api/content<br>Seite erstellen mit Wiki Markup"]
    I --> J{Mermaid-Code vorhanden?}
    J -->|Nein| M
    J -->|Ja| K["mmdc rendert Diagramm<br>Dark Theme, transparent, PNG"]
    K --> L["Confluence REST API: PUT /child/attachment<br>PNG als Attachment hochladen"]
    L --> M{Labels vorhanden?}
    M -->|Ja| N["Confluence REST API: POST /label<br>Labels setzen"]
    M -->|Nein| O
    N --> O[Server gibt Page-URL zurueck]
    O --> P[Agent zeigt Link + Zusammenfassung]

详细流程

步骤	组件	操作	API / 工具
1	User	在聊天中描述过程	Teams → Copilot
2	代理	检查完整性（标题 + 3 步骤）	系统提示符逻辑
3	代理	提取结构化数据	LLM推理
4	Agent	调用 MCP 工具	`create_confluence_doc` （6个字符串参数）
5	nginx	路由请求	`/mermaid/mcp` → `mcp-mermaid:3000/mcp`
6	服务器	解析塞米克隆监听	`parseList()`
7	服务器	山宁泰美人鱼代码	`\n` → 新线， `@` → `(at)`, `&` → `und`
8	服务器	构建 Wiki 标记	`buildWikiMarkup()` → h1、h2、#、*、{info}
9	服务器	创建 Confluence 页面	`POST /rest/api/content` （维基表示）
10	服务器	呈现图表	`mmdc -t dark -b transparent` → PNG
11	服务器	Lädt附件	`PUT /rest/api/content/{id}/child/attachment`
12	服务器	设置标签	`POST /rest/api/content/{id}/label`
13	代理	显示结果	页面 URL + 摘要

错误处理

情况	行为
标题已经存在	带日期后缀的自动重试（`Titel - 2026-02-19`)
Mermaid 渲染失败	仍在创建页面，响应中警告
标签设置失败	页面保留，响应中的警告
图中的特殊字符（`@`, `&`	服务器端备份清洁器

条件

Docker+Docker编写插件（v2）
公共服务器（用于本地开发的 Azure VM 或 ngrok）
微软365副驾驶工作室Zugang
Atlassian API代币(https://id.atlassian.com/manage-profile/security/api-tokens)

设置

1.配置环境

.env Confluence 访问数据文件：

CONFLUENCE_URL=https://your-domain.atlassian.net/wiki
CONFLUENCE_USERNAME=your-email@example.com
CONFLUENCE_API_TOKEN=your-api-token

可选（默认配置）：

CONFLUENCE_SPACE_KEY=~your-space-key
CONFLUENCE_PARENT_ID=your-parent-page-id

启动 Docker Stack

docker compose up -d

检查所有服务是否正在运行：

docker compose ps
# nginx-proxy-v2, mcp-atlassian-v2 (healthy), mcp-mermaid-v2

3a。当地开发 — ngrok Tunnel

ngrok http 127.0.0.1:8080

Windows 说明： ngrok http localhost:8080 失败，因为 localhost 祖 [::1] （IPv6）被解析，但Docker只绑定IPv4。总是 127.0.0.1 使用。

记下显示的 HTTPS URL （例如： https://abc123.ngrok-free.app).

3b。生产操作 — Azure VM

建议在每次重新启动时不更改URL的情况下永久运行。

先决条件：

Azure 中的 Ubuntu 24.04 公共 IP 虚拟机
在 Azure 网络安全组（NSG）中打开端口 80 和 443

设置 Azure DNS 标签（免费）：

Azure Portal → VM → Öffentliche IP → Konfiguration
→ DNS-Namensbezeichnung: z.B. "mcp-autodocbot"
→ Ergibt: mcp-autodocbot.germanywestcentral.cloudapp.azure.com

Docker编写插件安装程序：

sudo apt remove docker-compose -y
sudo apt install ca-certificates curl -y
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu noble stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update && sudo apt install docker-compose-plugin -y

使用Let's Encrypt的SSL证书：

sudo apt install nginx certbot python3-certbot-nginx -y
sudo ufw allow 80/tcp && sudo ufw allow 443/tcp

/etc/nginx/nginx.conf --im http { } 添加块（对于较长的 Azure 域名需要）：

http {
    server_names_hash_bucket_size 128;
    ...
}

sudo certbot --nginx -d mcp-autodocbot.germanywestcentral.cloudapp.azure.com

主机nginx als SSL终结者 (/etc/nginx/sites-available/mcp):

server {
    listen 443 ssl;
    server_name mcp-autodocbot.germanywestcentral.cloudapp.azure.com;

    ssl_certificate /etc/letsencrypt/live/mcp-autodocbot.germanywestcentral.cloudapp.azure.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp-autodocbot.germanywestcentral.cloudapp.azure.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

sudo ln -s /etc/nginx/sites-available/mcp /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

自动启动bei VM重新启动 (/etc/systemd/system/mcp.service):

[Unit]
Description=Auto-Doc-Bot MCP Stack
After=docker.service
Requires=docker.service

[Service]
WorkingDirectory=/home/<user>/mcp/V2
ExecStart=/usr/bin/docker compose up
ExecStop=/usr/bin/docker compose down
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl enable mcp && sudo systemctl start mcp

测试连接：

curl -X POST https://mcp-autodocbot.germanywestcentral.cloudapp.azure.com/mermaid/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

预期答案： {"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"..."},...}}

如何配置 Copilot Studio

在 Microsoft Copilot Studio 中创建新代理
将 MCP 服务器添加为工具提供程序：
- 当地： https://<ngrok-url>/mermaid/mcp
- 生产： https://mcp-autodocbot.germanywestcentral.cloudapp.azure.com/mermaid/mcp
内容 system_prompt.md 添加代理指令
发布和测试代理

项目结构

V2/
├── docker-compose.yml         ← Docker Stack (3 Services: nginx, mcp-atlassian, mcp-mermaid)
├── .env                       ← Confluence Credentials
├── mcp-mermaid/
│   ├── Dockerfile             ← Node 20 + Chromium + mmdc
│   ├── server.js              ← All-in-One MCP-Server (create_confluence_doc)
│   ├── package.json           ← Dependencies
│   └── puppeteer-config.json  ← Chromium --no-sandbox Config
├── mcp-server/
│   └── Dockerfile             ← Python 3.12 + mcp-atlassian (Backup, nicht aktiv)
├── nginx/
│   └── nginx.conf             ← Reverse Proxy (Pfad-Routing)
├── system_prompt.md           ← Copilot Agent Instructions
├── layout_template.md         ← Confluence Wiki Markup Template (Referenz)
├── SESSION_HISTORY.md         ← Entwicklungsprotokoll
└── README.md                  ← Diese Datei

MCP工具： `create_confluence_doc`

只有一个工具可以做到这一切。所有参数都是简单的字符串（分号作为分隔符）：

参数	描述	示例
`title`	页面标题	`Onboarding neuer Mitarbeiter`
`summary` 简要总结	`Ablauf fuer den ersten Arbeitstag`
`prerequisites` 条件（`;`分开或空）。 `Laptop bestellt; Zugaenge beantragt`
`steps` 过程步骤（`;`分开）。 `HR informiert IT; Unterlagen pruefen`
`mermaid_code` Mermaid Flowchart TD（或空白） `flowchart TD\n A[Start] --> B[Ende]`
`labels` 标签：类别 + 主题（`;`分开）。 `process; onboarding`

标签分类

类别	何时使用
`process`	一步一步的过程
`guideline` 准则，最佳实践。
`checklist` 检查清单
`troubleshooting`	错误修正
`reference` 参考，配置。

第二个标签=主题（自由，小写）：例如 onboarding, deployment, security, invoicing

已知的限制

ngrok免费等级： URL在每次重新启动时都会更改。需要在 Copilot Studio 中更新。用于生产：使用带有 DNS 标签的 Azure VM（请参阅设置 3b）。
副驾驶安全过滤器： 工具参数中的维基标记被阻止为提示注入（openAIIndirectAttack).因此，所有格式都是在服务器端完成的 - 代理只发送纯文本。
复杂的工具方案： Copilot Studio 不运行包含数组或嵌套对象的工具。因此，只有带分号分隔的简单字符串。
Mermaid 特殊字符： @, &, <, > 打破Mermaid语法。代理在图表中避免这些（仅在步骤中使用电子邮件地址等）。服务器备份补充清理。

技术细节

MCP传输

MCP服务器螺母 streamable-http （不是SSE）nginx路由器 /mermaid/mcp 端口3000的内部服务。工厂模式：每个 MCP 会话都有自己的 McpServer实例。

维基标记

Confluence Wiki Markup Syntax（非Markdown），在服务器端生成 buildWikiMarkup():

标题： h1. h2.
编号列表： # Schritt
列表： * Punkt
信息面板： {info:title=Titel}Text{info}
可折叠区域： {expand:title=Titel}Inhalt{expand}
附件图片： !dateiname.svg! （最好是SVG，最好是PNG）

美人鱼渲染

服务器端通过 mmdc （@mermaid js/mermaid cli）mit Chromium
黑暗主题(-t dark（透明背景）-b transparent)
文字 \n 从LLM自动转换为真正的新线
特殊字符回归： @ → (at), & → und

使用说明

自动文档机器人

建筑

详细流程

详细流程

错误处理

条件

设置

1.配置环境

启动 Docker Stack

3a。当地开发 — ngrok Tunnel

3b。生产操作 — Azure VM

如何配置 Copilot Studio

项目结构

MCP工具： create_confluence_doc

标签分类

已知的限制

技术细节

MCP传输

维基标记

美人鱼渲染

相关 MCP

Confluence文档搜索与管理服务

API文档生成服务

Confluence文档查询服务

Confluence文档生成服务

Confluence集成服务器

Jira智能分析工具

MCP工具： `create_confluence_doc`