@muleiwu/mdoc-mcp 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add:*)",
+      "Bash(git commit:*)"
+    ]
+  }
+}

package/.env.example

@@ -0,0 +1,8 @@
+# mdoc API Key（必需）
+# 在 mdoc 用户设置页面创建 API Key 后获取
+MDOC_ACCESS_KEY_ID=your_access_key_id_here
+MDOC_SECRET_ACCESS_KEY=your_secret_access_key_here
+
+# API 基础地址（可选，默认 https://mdoc.cc）
+# 如果使用私有部署，请修改此地址
+# MDOC_API_BASE_URL=https://mdoc.cc

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 muleiwu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# mdoc-mcp
+
+[mdoc](https://mdoc.cc) 的 MCP (Model Context Protocol) Server，让 AI 能够直接读取 mdoc 文档的目录结构和文章内容。
+
+## 功能
+
+- **`get_manifest`** — 获取文档目录清单（Markdown 格式），包含所有文章的层级结构和链接
+- **`get_article_content`** — 获取文章的原始 Markdown 内容
+
+## 安装与配置
+
+### 1. 克隆并构建
+
+```bash
+git clone https://github.com/muleiwu/mdoc-mcp.git
+cd mdoc-mcp
+npm install
+npm run build
+```
+
+### 2. 配置 API Key
+
+在 [mdoc](https://mdoc.cc) 用户设置页面创建 API Key，获取 `AccessKeyID` 和 `SecretAccessKey`。
+
+鉴权使用 AWS Signature Version 4 协议，与服务端完全兼容。
+
+### 3. 在 Cursor / Claude Desktop 中配置
+
+编辑 MCP 配置文件（如 `~/.cursor/mcp.json` 或 Claude Desktop 的配置），添加：
+
+```json
+{
+  "mcpServers": {
+    "mdoc": {
+      "command": "node",
+      "args": ["/path/to/mdoc-mcp/dist/index.js"],
+      "env": {
+        "MDOC_ACCESS_KEY_ID": "your_access_key_id",
+        "MDOC_SECRET_ACCESS_KEY": "your_secret_access_key"
+      }
+    }
+  }
+}
+```
+
+如果使用私有部署的 mdoc，额外添加：
+
+```json
+"MDOC_API_BASE_URL": "https://your-mdoc-instance.com"
+```
+
+## 工具说明
+
+### `get_manifest` — 获取文档目录
+
+获取文档的完整目录清单，AI 可据此了解文档结构并选择要读取的文章。
+
+**参数**（提供 `url` 或 `orgSlug` + `docSlug` 之一）：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `url` | string (可选) | mdoc 网址，如 `https://mdoc.cc/mliev/1ms` 或带版本 `https://mdoc.cc/mliev/1ms/v1.0.0` |
+| `orgSlug` | string (可选) | 组织标识，如 `mliev` |
+| `docSlug` | string (可选) | 文档标识，如 `1ms` |
+| `version` | string (可选) | 版本名称，如 `v1.0.0`，不指定则使用默认版本 |
+
+**返回**：Markdown 格式的文档目录，包含文章链接（可直接用于 `get_article_content`）
+
+### `get_article_content` — 获取文章内容
+
+获取指定文章的原始 Markdown 内容。
+
+**参数**（提供 `url` 或 `orgSlug` + `docSlug` + `articleId` 之一）：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `url` | string (可选) | 网址或 manifest 中的 content.md 链接 |
+| `orgSlug` | string (可选) | 组织标识 |
+| `docSlug` | string (可选) | 文档标识 |
+| `articleId` | string (可选) | 文章 ID |
+| `version` | string (可选) | 版本名称 |
+
+支持的 `url` 格式：
+- `https://mdoc.cc/mliev/1ms/v1.0.0/16`（mdoc 网址，第 4 段为 articleId）
+- `https://mdoc.cc/openapi/organizations/mliev/documents/1ms/articles/16/content.md`（manifest 返回的 API 链接）
+
+## 典型使用流程
+
+1. AI 调用 `get_manifest` 获取文档目录
+2. 从目录中找到相关文章的链接
+3. AI 调用 `get_article_content` 读取具体文章内容
+
+## 环境变量
+
+| 变量 | 必需 | 默认值 | 说明 |
+|------|------|--------|------|
+| `MDOC_ACCESS_KEY_ID` | 是 | — | API Key 的 Access Key ID |
+| `MDOC_SECRET_ACCESS_KEY` | 是 | — | API Key 的 Secret Access Key |
+| `MDOC_API_BASE_URL` | 否 | `https://mdoc.cc` | API 基础地址（私有部署时使用） |
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+export interface MdocClientConfig {
+    accessKeyId: string;
+    secretAccessKey: string;
+    baseUrl: string;
+}
+export interface RequestOptions {
+    path: string;
+    query?: Record<string, string>;
+}
+export declare class MdocClient {
+    private config;
+    private readonly service;
+    private readonly region;
+    constructor(config: MdocClientConfig);
+    /**
+     * 发起带 AWS Signature V4 签名的 GET 请求
+     */
+    get(options: RequestOptions): Promise<string>;
+}
+/**
+ * 从环境变量创建客户端实例
+ */
+export declare function createClientFromEnv(): MdocClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AA4ED,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;gBAE1B,MAAM,EAAE,gBAAgB;IAIpC;;OAEG;IACG,GAAG,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;CA+DpD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,UAAU,CAahD"}

package/dist/client.js

@@ -0,0 +1,121 @@
+import { createHmac, createHash } from 'crypto';
+import { request as httpsRequest } from 'https';
+import { request as httpRequest } from 'http';
+function hmac(key, data) {
+    return createHmac('sha256', key).update(data).digest();
+}
+function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/**
+ * 构建 AWS Signature V4 Authorization 头
+ *
+ * 注意：Go 的 net/http 服务器会将 Host 头从 req.Header 移到 req.Host，
+ * 导致 gohttpsig 的 CanonicalizeHeaders 无法找到 host 的值。
+ * 因此这里签名时不包含 host 头，只签 x-amz-date。
+ */
+function buildAuthHeader(accessKeyId, secretAccessKey, method, path, query, dateTime, service, region) {
+    const dateShort = dateTime.slice(0, 8);
+    // 只签 x-amz-date（不含 host，因为服务端 Go HTTP 会将 Host 头移出 req.Header）
+    const signedHeaders = 'x-amz-date';
+    const canonicalHeaders = `x-amz-date:${dateTime}\n`;
+    const payloadHash = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'; // SHA256("")
+    const canonicalRequest = [
+        method,
+        path,
+        query,
+        canonicalHeaders,
+        signedHeaders,
+        payloadHash,
+    ].join('\n');
+    const credentialScope = `${dateShort}/${region}/${service}/aws4_request`;
+    const stringToSign = [
+        'AWS4-HMAC-SHA256',
+        dateTime,
+        credentialScope,
+        sha256Hex(canonicalRequest),
+    ].join('\n');
+    const signingKey = hmac(hmac(hmac(hmac(`AWS4${secretAccessKey}`, dateShort), region), service), 'aws4_request');
+    const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex');
+    return `AWS4-HMAC-SHA256 Credential=${accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+}
+function readBody(res) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        res.on('error', reject);
+    });
+}
+export class MdocClient {
+    config;
+    service = 'mdoc';
+    region = 'us-east-1';
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * 发起带 AWS Signature V4 签名的 GET 请求
+     */
+    async get(options) {
+        const url = new URL(this.config.baseUrl);
+        const isHttps = url.protocol === 'https:';
+        const host = url.hostname;
+        const port = url.port
+            ? parseInt(url.port)
+            : isHttps ? 443 : 80;
+        // 构建查询字符串（按 key 排序，符合 AWS 规范）
+        let queryString = '';
+        if (options.query && Object.keys(options.query).length > 0) {
+            const filtered = Object.entries(options.query).filter(([, v]) => v !== undefined && v !== '');
+            queryString = filtered
+                .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+                .sort()
+                .join('&');
+        }
+        const fullPath = queryString ? `${options.path}?${queryString}` : options.path;
+        // 生成时间戳（ISO8601 格式，去除特殊字符）
+        const dateTime = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+        // 构建 Authorization 头
+        const authHeader = buildAuthHeader(this.config.accessKeyId, this.config.secretAccessKey, 'GET', options.path, queryString, dateTime, this.service, this.region);
+        return new Promise((resolve, reject) => {
+            const reqOptions = {
+                hostname: host,
+                port,
+                path: fullPath,
+                method: 'GET',
+                headers: {
+                    'X-Amz-Date': dateTime,
+                    'Authorization': authHeader,
+                },
+            };
+            const req = (isHttps ? httpsRequest : httpRequest)(reqOptions, async (res) => {
+                const body = await readBody(res);
+                const statusCode = res.statusCode ?? 0;
+                if (statusCode >= 400) {
+                    reject(new Error(`HTTP ${statusCode}: ${body}`));
+                    return;
+                }
+                resolve(body);
+            });
+            req.on('error', reject);
+            req.end();
+        });
+    }
+}
+/**
+ * 从环境变量创建客户端实例
+ */
+export function createClientFromEnv() {
+    const accessKeyId = process.env.MDOC_ACCESS_KEY_ID;
+    const secretAccessKey = process.env.MDOC_SECRET_ACCESS_KEY;
+    const baseUrl = process.env.MDOC_API_BASE_URL ?? 'https://mdoc.cc';
+    if (!accessKeyId) {
+        throw new Error('缺少环境变量 MDOC_ACCESS_KEY_ID');
+    }
+    if (!secretAccessKey) {
+        throw new Error('缺少环境变量 MDOC_SECRET_ACCESS_KEY');
+    }
+    return new MdocClient({ accessKeyId, secretAccessKey, baseUrl });
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,MAAM,CAAC;AAc9C,SAAS,IAAI,CAAC,GAAoB,EAAE,IAAY;IAC9C,OAAO,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;AACzD,CAAC;AAED,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CACtB,WAAmB,EACnB,eAAuB,EACvB,MAAc,EACd,IAAY,EACZ,KAAa,EACb,QAAgB,EAChB,OAAe,EACf,MAAc;IAEd,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAEvC,8DAA8D;IAC9D,MAAM,aAAa,GAAG,YAAY,CAAC;IACnC,MAAM,gBAAgB,GAAG,cAAc,QAAQ,IAAI,CAAC;IACpD,MAAM,WAAW,GAAG,kEAAkE,CAAC,CAAC,aAAa;IAErG,MAAM,gBAAgB,GAAG;QACvB,MAAM;QACN,IAAI;QACJ,KAAK;QACL,gBAAgB;QAChB,aAAa;QACb,WAAW;KACZ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,MAAM,eAAe,GAAG,GAAG,SAAS,IAAI,MAAM,IAAI,OAAO,eAAe,CAAC;IACzE,MAAM,YAAY,GAAG;QACnB,kBAAkB;QAClB,QAAQ;QACR,eAAe;QACf,SAAS,CAAC,gBAAgB,CAAC;KAC5B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,MAAM,UAAU,GAAG,IAAI,CACrB,IAAI,CACF,IAAI,CACF,IAAI,CAAC,OAAO,eAAe,EAAE,EAAE,SAAS,CAAC,EACzC,MAAM,CACP,EACD,OAAO,CACR,EACD,cAAc,CACf,CAAC;IAEF,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEtF,OAAO,+BAA+B,WAAW,IAAI,eAAe,mBAAmB,aAAa,eAAe,SAAS,EAAE,CAAC;AACjI,CAAC;AAED,SAAS,QAAQ,CAAC,GAAoB;IACpC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACtD,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACtE,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,OAAO,UAAU;IACb,MAAM,CAAmB;IAChB,OAAO,GAAG,MAAM,CAAC;IACjB,MAAM,GAAG,WAAW,CAAC;IAEtC,YAAY,MAAwB;QAClC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,OAAuB;QAC/B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC;QAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC;QAC1B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI;YACnB,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;YACpB,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAEvB,8BAA8B;QAC9B,IAAI,WAAW,GAAG,EAAE,CAAC;QACrB,IAAI,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3D,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YAC9F,WAAW,GAAG,QAAQ;iBACnB,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;iBACpE,IAAI,EAAE;iBACN,IAAI,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;QAED,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;QAE/E,2BAA2B;QAC3B,MAAM,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAEtF,qBAAqB;QACrB,MAAM,UAAU,GAAG,eAAe,CAChC,IAAI,CAAC,MAAM,CAAC,WAAW,EACvB,IAAI,CAAC,MAAM,CAAC,eAAe,EAC3B,KAAK,EACL,OAAO,CAAC,IAAI,EACZ,WAAW,EACX,QAAQ,EACR,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,MAAM,CACZ,CAAC;QAEF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,UAAU,GAAG;gBACjB,QAAQ,EAAE,IAAI;gBACd,IAAI;gBACJ,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE;oBACP,YAAY,EAAE,QAAQ;oBACtB,eAAe,EAAE,UAAU;iBACF;aAC5B,CAAC;YAEF,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC3E,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;gBACjC,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,IAAI,CAAC,CAAC;gBAEvC,IAAI,UAAU,IAAI,GAAG,EAAE,CAAC;oBACtB,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,UAAU,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;oBACjD,OAAO;gBACT,CAAC;gBAED,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC,CAAC,CAAC;YAEH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACxB,GAAG,CAAC,GAAG,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IACnD,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;IAC3D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,iBAAiB,CAAC;IAEnE,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,IAAI,UAAU,CAAC,EAAE,WAAW,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,CAAC;AACnE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as z from 'zod/v4';
+import { createClientFromEnv } from './client.js';
+import { getManifest } from './tools/get-manifest.js';
+import { getArticleContent } from './tools/get-article-content.js';
+const server = new McpServer({
+    name: 'mdoc-mcp',
+    version: '0.1.0',
+});
+// Tool: get_manifest
+server.registerTool('get_manifest', {
+    title: '获取文档目录清单',
+    description: '获取 mdoc 文档的目录清单（Markdown 格式），包含所有文章的标题和链接。' +
+        '可以通过 mdoc.cc 网址或 orgSlug/docSlug 参数指定文档。' +
+        '示例网址格式：https://mdoc.cc/mliev/1ms 或 https://mdoc.cc/mliev/1ms/v1.0.0',
+    inputSchema: {
+        url: z
+            .string()
+            .optional()
+            .describe('mdoc 文档网址，如 https://mdoc.cc/mliev/1ms 或 https://mdoc.cc/mliev/1ms/v1.0.0。' +
+            '提供 url 时，orgSlug 和 docSlug 可省略。'),
+        orgSlug: z
+            .string()
+            .optional()
+            .describe('组织标识，如 mliev。当未提供 url 时必填。'),
+        docSlug: z
+            .string()
+            .optional()
+            .describe('文档标识，如 1ms。当未提供 url 时必填。'),
+        version: z
+            .string()
+            .optional()
+            .describe('版本名称，如 v1.0.0。不指定则使用文档默认版本。'),
+    },
+}, async (args) => {
+    try {
+        const client = createClientFromEnv();
+        const content = await getManifest(client, args);
+        return {
+            content: [{ type: 'text', text: content }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: 'text', text: `错误: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: get_article_content
+server.registerTool('get_article_content', {
+    title: '获取文章内容',
+    description: '获取 mdoc 文档中某篇文章的原始 Markdown 内容。' +
+        '可通过 mdoc.cc 网址（含 articleId）、manifest 返回的 content.md 链接，' +
+        '或 orgSlug/docSlug/articleId 参数指定文章。' +
+        '示例网址格式：https://mdoc.cc/mliev/1ms/v1.0.0/16',
+    inputSchema: {
+        url: z
+            .string()
+            .optional()
+            .describe('文章网址，支持两种格式：\n' +
+            '1. mdoc.cc 网址：https://mdoc.cc/mliev/1ms/v1.0.0/16\n' +
+            '2. manifest 中返回的 content.md API 链接，如 ' +
+            'https://mdoc.cc/openapi/organizations/mliev/documents/1ms/articles/16/content.md'),
+        orgSlug: z
+            .string()
+            .optional()
+            .describe('组织标识，如 mliev。当未提供 url 时必填。'),
+        docSlug: z
+            .string()
+            .optional()
+            .describe('文档标识，如 1ms。当未提供 url 时必填。'),
+        articleId: z
+            .string()
+            .optional()
+            .describe('文章 ID，如 16。当未提供 url 时必填。'),
+        version: z
+            .string()
+            .optional()
+            .describe('版本名称，如 v1.0.0。不指定则使用文档默认版本。'),
+    },
+}, async (args) => {
+    try {
+        const client = createClientFromEnv();
+        const content = await getArticleContent(client, args);
+        return {
+            content: [{ type: 'text', text: content }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: 'text', text: `错误: ${message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // 使用 stderr 避免干扰 stdio 传输协议
+    process.stderr.write('mdoc MCP server 已启动（stdio 模式）\n');
+}
+main().catch((error) => {
+    process.stderr.write(`启动失败: ${error}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/get-article-content.d.ts

@@ -0,0 +1,18 @@
+import { MdocClient } from '../client.js';
+export interface GetArticleContentInput {
+    url?: string;
+    orgSlug?: string;
+    docSlug?: string;
+    articleId?: string;
+    version?: string;
+}
+/**
+ * 获取文章的原始 Markdown 内容
+ * 对应 API: GET /openapi/organizations/:orgSlug/documents/:docSlug/articles/:articleId/content.md
+ *
+ * url 参数支持两种格式：
+ * 1. mdoc.cc 网址: https://mdoc.cc/:orgSlug/:docSlug/:version/:articleId
+ * 2. API content URL: .../openapi/organizations/.../articles/:articleId/content.md
+ */
+export declare function getArticleContent(client: MdocClient, input: GetArticleContentInput): Promise<string>;
+//# sourceMappingURL=get-article-content.d.ts.map

package/dist/tools/get-article-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-article-content.d.ts","sourceRoot":"","sources":["../../src/tools/get-article-content.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,MAAM,WAAW,sBAAsB;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,MAAM,CAAC,CA2CjB"}

package/dist/tools/get-article-content.js

@@ -0,0 +1,45 @@
+import { parseMdocUrl } from '../url-parser.js';
+/**
+ * 获取文章的原始 Markdown 内容
+ * 对应 API: GET /openapi/organizations/:orgSlug/documents/:docSlug/articles/:articleId/content.md
+ *
+ * url 参数支持两种格式：
+ * 1. mdoc.cc 网址: https://mdoc.cc/:orgSlug/:docSlug/:version/:articleId
+ * 2. API content URL: .../openapi/organizations/.../articles/:articleId/content.md
+ */
+export async function getArticleContent(client, input) {
+    let orgSlug;
+    let docSlug;
+    let articleId;
+    let version = input.version;
+    if (input.url) {
+        const parsed = parseMdocUrl(input.url);
+        if (!parsed.articleId) {
+            throw new Error(`无法从 URL 中解析出 articleId，请确认 URL 格式正确（如 https://mdoc.cc/org/doc/v1.0.0/16），` +
+                `或单独提供 orgSlug、docSlug 和 articleId 参数`);
+        }
+        orgSlug = parsed.orgSlug;
+        docSlug = parsed.docSlug;
+        articleId = parsed.articleId;
+        if (!version && parsed.version) {
+            version = parsed.version;
+        }
+    }
+    else if (input.orgSlug && input.docSlug && input.articleId) {
+        orgSlug = input.orgSlug;
+        docSlug = input.docSlug;
+        articleId = input.articleId;
+    }
+    else {
+        throw new Error('请提供 url 参数，或同时提供 orgSlug、docSlug 和 articleId 参数');
+    }
+    const path = `/openapi/organizations/${encodeURIComponent(orgSlug)}` +
+        `/documents/${encodeURIComponent(docSlug)}` +
+        `/articles/${encodeURIComponent(articleId)}/content.md`;
+    const query = {};
+    if (version) {
+        query['version'] = version;
+    }
+    return client.get({ path, query });
+}
+//# sourceMappingURL=get-article-content.js.map

package/dist/tools/get-article-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-article-content.js","sourceRoot":"","sources":["../../src/tools/get-article-content.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAUhD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAkB,EAClB,KAA6B;IAE7B,IAAI,OAAe,CAAC;IACpB,IAAI,OAAe,CAAC;IACpB,IAAI,SAAiB,CAAC;IACtB,IAAI,OAAO,GAAuB,KAAK,CAAC,OAAO,CAAC;IAEhD,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;QACd,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAEvC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,2EAA2E;gBAC3E,sCAAsC,CACvC,CAAC;QACJ,CAAC;QAED,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QACzB,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QACzB,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAC7B,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAC/B,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC3B,CAAC;IACH,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAC7D,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QACxB,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QACxB,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAC9B,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CACb,iDAAiD,CAClD,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GACR,0BAA0B,kBAAkB,CAAC,OAAO,CAAC,EAAE;QACvD,cAAc,kBAAkB,CAAC,OAAO,CAAC,EAAE;QAC3C,aAAa,kBAAkB,CAAC,SAAS,CAAC,aAAa,CAAC;IAE1D,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,IAAI,OAAO,EAAE,CAAC;QACZ,KAAK,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC;IAC7B,CAAC;IAED,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACrC,CAAC"}

package/dist/tools/get-manifest.d.ts

@@ -0,0 +1,13 @@
+import { MdocClient } from '../client.js';
+export interface GetManifestInput {
+    url?: string;
+    orgSlug?: string;
+    docSlug?: string;
+    version?: string;
+}
+/**
+ * 获取文档目录清单（Markdown 格式）
+ * 对应 API: GET /openapi/organizations/:orgSlug/documents/:docSlug/manifest
+ */
+export declare function getManifest(client: MdocClient, input: GetManifestInput): Promise<string>;
+//# sourceMappingURL=get-manifest.d.ts.map

package/dist/tools/get-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-manifest.d.ts","sourceRoot":"","sources":["../../src/tools/get-manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,MAAM,CAAC,CA2BjB"}

package/dist/tools/get-manifest.js

@@ -0,0 +1,33 @@
+import { parseMdocUrl } from '../url-parser.js';
+/**
+ * 获取文档目录清单（Markdown 格式）
+ * 对应 API: GET /openapi/organizations/:orgSlug/documents/:docSlug/manifest
+ */
+export async function getManifest(client, input) {
+    let orgSlug;
+    let docSlug;
+    let version = input.version;
+    if (input.url) {
+        const parsed = parseMdocUrl(input.url);
+        orgSlug = parsed.orgSlug;
+        docSlug = parsed.docSlug;
+        // URL 中解析到的版本优先级低于显式传入的 version 参数
+        if (!version && parsed.version) {
+            version = parsed.version;
+        }
+    }
+    else if (input.orgSlug && input.docSlug) {
+        orgSlug = input.orgSlug;
+        docSlug = input.docSlug;
+    }
+    else {
+        throw new Error('请提供 url 参数，或同时提供 orgSlug 和 docSlug 参数');
+    }
+    const path = `/openapi/organizations/${encodeURIComponent(orgSlug)}/documents/${encodeURIComponent(docSlug)}/manifest`;
+    const query = {};
+    if (version) {
+        query['version'] = version;
+    }
+    return client.get({ path, query });
+}
+//# sourceMappingURL=get-manifest.js.map

package/dist/tools/get-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-manifest.js","sourceRoot":"","sources":["../../src/tools/get-manifest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAShD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAkB,EAClB,KAAuB;IAEvB,IAAI,OAAe,CAAC;IACpB,IAAI,OAAe,CAAC;IACpB,IAAI,OAAO,GAAuB,KAAK,CAAC,OAAO,CAAC;IAEhD,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;QACd,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACvC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QACzB,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QACzB,mCAAmC;QACnC,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAC/B,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC3B,CAAC;IACH,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAC1C,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QACxB,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC1B,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,MAAM,IAAI,GAAG,0BAA0B,kBAAkB,CAAC,OAAO,CAAC,cAAc,kBAAkB,CAAC,OAAO,CAAC,WAAW,CAAC;IACvH,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,IAAI,OAAO,EAAE,CAAC;QACZ,KAAK,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC;IAC7B,CAAC;IAED,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACrC,CAAC"}

package/dist/url-parser.d.ts

@@ -0,0 +1,24 @@
+/**
+ * mdoc URL 解析器
+ *
+ * 支持以下格式：
+ * 1. mdoc.cc 网站 URL:
+ *    - https://mdoc.cc/:orgSlug/:docSlug
+ *    - https://mdoc.cc/:orgSlug/:docSlug/:version
+ *    - https://mdoc.cc/:orgSlug/:docSlug/:version/:articleId
+ *
+ * 2. OpenAPI content URL (从 manifest 返回的链接):
+ *    - .../openapi/organizations/:orgSlug/documents/:docSlug/articles/:articleId/content.md
+ */
+export interface ParsedMdocUrl {
+    orgSlug: string;
+    docSlug: string;
+    version?: string;
+    articleId?: string;
+}
+/**
+ * 解析 mdoc URL，提取参数
+ * @throws {Error} 如果 URL 格式无法识别
+ */
+export declare function parseMdocUrl(rawUrl: string): ParsedMdocUrl;
+//# sourceMappingURL=url-parser.d.ts.map

package/dist/url-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-parser.d.ts","sourceRoot":"","sources":["../src/url-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiBD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CA0E1D"}

package/dist/url-parser.js

@@ -0,0 +1,94 @@
+/**
+ * mdoc URL 解析器
+ *
+ * 支持以下格式：
+ * 1. mdoc.cc 网站 URL:
+ *    - https://mdoc.cc/:orgSlug/:docSlug
+ *    - https://mdoc.cc/:orgSlug/:docSlug/:version
+ *    - https://mdoc.cc/:orgSlug/:docSlug/:version/:articleId
+ *
+ * 2. OpenAPI content URL (从 manifest 返回的链接):
+ *    - .../openapi/organizations/:orgSlug/documents/:docSlug/articles/:articleId/content.md
+ */
+/**
+ * 判断字符串是否看起来像版本号（以字母开头，如 v1.0.0，或纯数字组成的版本）
+ * 版本号特征：包含字母前缀或包含点号
+ */
+function looksLikeVersion(segment) {
+    return /^v\d/.test(segment) || /^\d+\.\d+/.test(segment);
+}
+/**
+ * 判断字符串是否看起来像文章 ID（纯数字）
+ */
+function looksLikeArticleId(segment) {
+    return /^\d+$/.test(segment);
+}
+/**
+ * 解析 mdoc URL，提取参数
+ * @throws {Error} 如果 URL 格式无法识别
+ */
+export function parseMdocUrl(rawUrl) {
+    // 补全协议头
+    if (!rawUrl.startsWith('http://') && !rawUrl.startsWith('https://')) {
+        rawUrl = 'https://' + rawUrl;
+    }
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new Error(`无效的 URL 格式: ${rawUrl}`);
+    }
+    const pathname = url.pathname;
+    // 去掉首尾斜杠，拆分路径段
+    const segments = pathname.replace(/^\/|\/$/g, '').split('/').filter(Boolean);
+    // 尝试匹配 OpenAPI content URL:
+    // /openapi/organizations/:orgSlug/documents/:docSlug/articles/:articleId/content.md
+    const openapiMatch = pathname.match(/\/openapi\/organizations\/([^/]+)\/documents\/([^/]+)\/articles\/([^/]+)\/content\.md/);
+    if (openapiMatch) {
+        return {
+            orgSlug: openapiMatch[1],
+            docSlug: openapiMatch[2],
+            articleId: openapiMatch[3],
+        };
+    }
+    // 尝试匹配 OpenAPI manifest URL:
+    // /openapi/organizations/:orgSlug/documents/:docSlug/manifest
+    const manifestMatch = pathname.match(/\/openapi\/organizations\/([^/]+)\/documents\/([^/]+)\/manifest/);
+    if (manifestMatch) {
+        const version = url.searchParams.get('version') ?? undefined;
+        return {
+            orgSlug: manifestMatch[1],
+            docSlug: manifestMatch[2],
+            version,
+        };
+    }
+    // 解析 mdoc.cc 风格的网址: /:orgSlug/:docSlug[/:version[/:articleId]]
+    if (segments.length < 2) {
+        throw new Error(`URL 路径段不足，期望格式: /:orgSlug/:docSlug[/:version[/:articleId]]，实际路径: ${pathname}`);
+    }
+    const [orgSlug, docSlug, seg3, seg4] = segments;
+    let version;
+    let articleId;
+    if (seg3) {
+        if (looksLikeArticleId(seg3) && !seg4) {
+            // 只有纯数字且没有第四段：当做 articleId
+            articleId = seg3;
+        }
+        else if (looksLikeVersion(seg3)) {
+            version = seg3;
+            if (seg4) {
+                articleId = seg4;
+            }
+        }
+        else {
+            // 第三段既不像版本也不像 articleId，作为 version 兜底处理
+            version = seg3;
+            if (seg4) {
+                articleId = seg4;
+            }
+        }
+    }
+    return { orgSlug, docSlug, version, articleId };
+}
+//# sourceMappingURL=url-parser.js.map

package/dist/url-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-parser.js","sourceRoot":"","sources":["../src/url-parser.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@muleiwu/mdoc-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for mdoc document reading via OpenAPI",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mdoc-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,184 @@
+import { createHmac, createHash } from 'crypto';
+import { request as httpsRequest } from 'https';
+import { request as httpRequest } from 'http';
+import { IncomingMessage } from 'http';
+
+export interface MdocClientConfig {
+  accessKeyId: string;
+  secretAccessKey: string;
+  baseUrl: string;
+}
+
+export interface RequestOptions {
+  path: string;
+  query?: Record<string, string>;
+}
+
+function hmac(key: Buffer | string, data: string): Buffer {
+  return createHmac('sha256', key).update(data).digest();
+}
+
+function sha256Hex(data: string): string {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * 构建 AWS Signature V4 Authorization 头
+ *
+ * 注意：Go 的 net/http 服务器会将 Host 头从 req.Header 移到 req.Host，
+ * 导致 gohttpsig 的 CanonicalizeHeaders 无法找到 host 的值。
+ * 因此这里签名时不包含 host 头，只签 x-amz-date。
+ */
+function buildAuthHeader(
+  accessKeyId: string,
+  secretAccessKey: string,
+  method: string,
+  path: string,
+  query: string,
+  dateTime: string,
+  service: string,
+  region: string
+): string {
+  const dateShort = dateTime.slice(0, 8);
+
+  // 只签 x-amz-date（不含 host，因为服务端 Go HTTP 会将 Host 头移出 req.Header）
+  const signedHeaders = 'x-amz-date';
+  const canonicalHeaders = `x-amz-date:${dateTime}\n`;
+  const payloadHash = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'; // SHA256("")
+
+  const canonicalRequest = [
+    method,
+    path,
+    query,
+    canonicalHeaders,
+    signedHeaders,
+    payloadHash,
+  ].join('\n');
+
+  const credentialScope = `${dateShort}/${region}/${service}/aws4_request`;
+  const stringToSign = [
+    'AWS4-HMAC-SHA256',
+    dateTime,
+    credentialScope,
+    sha256Hex(canonicalRequest),
+  ].join('\n');
+
+  const signingKey = hmac(
+    hmac(
+      hmac(
+        hmac(`AWS4${secretAccessKey}`, dateShort),
+        region
+      ),
+      service
+    ),
+    'aws4_request'
+  );
+
+  const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex');
+
+  return `AWS4-HMAC-SHA256 Credential=${accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+}
+
+function readBody(res: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    res.on('data', (chunk: Buffer) => chunks.push(chunk));
+    res.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+    res.on('error', reject);
+  });
+}
+
+export class MdocClient {
+  private config: MdocClientConfig;
+  private readonly service = 'mdoc';
+  private readonly region = 'us-east-1';
+
+  constructor(config: MdocClientConfig) {
+    this.config = config;
+  }
+
+  /**
+   * 发起带 AWS Signature V4 签名的 GET 请求
+   */
+  async get(options: RequestOptions): Promise<string> {
+    const url = new URL(this.config.baseUrl);
+    const isHttps = url.protocol === 'https:';
+    const host = url.hostname;
+    const port = url.port
+      ? parseInt(url.port)
+      : isHttps ? 443 : 80;
+
+    // 构建查询字符串（按 key 排序，符合 AWS 规范）
+    let queryString = '';
+    if (options.query && Object.keys(options.query).length > 0) {
+      const filtered = Object.entries(options.query).filter(([, v]) => v !== undefined && v !== '');
+      queryString = filtered
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+        .sort()
+        .join('&');
+    }
+
+    const fullPath = queryString ? `${options.path}?${queryString}` : options.path;
+
+    // 生成时间戳（ISO8601 格式，去除特殊字符）
+    const dateTime = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+
+    // 构建 Authorization 头
+    const authHeader = buildAuthHeader(
+      this.config.accessKeyId,
+      this.config.secretAccessKey,
+      'GET',
+      options.path,
+      queryString,
+      dateTime,
+      this.service,
+      this.region
+    );
+
+    return new Promise((resolve, reject) => {
+      const reqOptions = {
+        hostname: host,
+        port,
+        path: fullPath,
+        method: 'GET',
+        headers: {
+          'X-Amz-Date': dateTime,
+          'Authorization': authHeader,
+        } as Record<string, string>,
+      };
+
+      const req = (isHttps ? httpsRequest : httpRequest)(reqOptions, async (res) => {
+        const body = await readBody(res);
+        const statusCode = res.statusCode ?? 0;
+
+        if (statusCode >= 400) {
+          reject(new Error(`HTTP ${statusCode}: ${body}`));
+          return;
+        }
+
+        resolve(body);
+      });
+
+      req.on('error', reject);
+      req.end();
+    });
+  }
+}
+
+/**
+ * 从环境变量创建客户端实例
+ */
+export function createClientFromEnv(): MdocClient {
+  const accessKeyId = process.env.MDOC_ACCESS_KEY_ID;
+  const secretAccessKey = process.env.MDOC_SECRET_ACCESS_KEY;
+  const baseUrl = process.env.MDOC_API_BASE_URL ?? 'https://mdoc.cc';
+
+  if (!accessKeyId) {
+    throw new Error('缺少环境变量 MDOC_ACCESS_KEY_ID');
+  }
+  if (!secretAccessKey) {
+    throw new Error('缺少环境变量 MDOC_SECRET_ACCESS_KEY');
+  }
+
+  return new MdocClient({ accessKeyId, secretAccessKey, baseUrl });
+}

package/src/index.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as z from 'zod/v4';
+import { createClientFromEnv } from './client.js';
+import { getManifest } from './tools/get-manifest.js';
+import { getArticleContent } from './tools/get-article-content.js';
+
+const server = new McpServer({
+  name: 'mdoc-mcp',
+  version: '0.1.0',
+});
+
+// Tool: get_manifest
+server.registerTool(
+  'get_manifest',
+  {
+    title: '获取文档目录清单',
+    description:
+      '获取 mdoc 文档的目录清单（Markdown 格式），包含所有文章的标题和链接。' +
+      '可以通过 mdoc.cc 网址或 orgSlug/docSlug 参数指定文档。' +
+      '示例网址格式：https://mdoc.cc/mliev/1ms 或 https://mdoc.cc/mliev/1ms/v1.0.0',
+    inputSchema: {
+      url: z
+        .string()
+        .optional()
+        .describe(
+          'mdoc 文档网址，如 https://mdoc.cc/mliev/1ms 或 https://mdoc.cc/mliev/1ms/v1.0.0。' +
+          '提供 url 时，orgSlug 和 docSlug 可省略。'
+        ),
+      orgSlug: z
+        .string()
+        .optional()
+        .describe('组织标识，如 mliev。当未提供 url 时必填。'),
+      docSlug: z
+        .string()
+        .optional()
+        .describe('文档标识，如 1ms。当未提供 url 时必填。'),
+      version: z
+        .string()
+        .optional()
+        .describe('版本名称，如 v1.0.0。不指定则使用文档默认版本。'),
+    },
+  },
+  async (args) => {
+    try {
+      const client = createClientFromEnv();
+      const content = await getManifest(client, args);
+      return {
+        content: [{ type: 'text', text: content }],
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        content: [{ type: 'text', text: `错误: ${message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Tool: get_article_content
+server.registerTool(
+  'get_article_content',
+  {
+    title: '获取文章内容',
+    description:
+      '获取 mdoc 文档中某篇文章的原始 Markdown 内容。' +
+      '可通过 mdoc.cc 网址（含 articleId）、manifest 返回的 content.md 链接，' +
+      '或 orgSlug/docSlug/articleId 参数指定文章。' +
+      '示例网址格式：https://mdoc.cc/mliev/1ms/v1.0.0/16',
+    inputSchema: {
+      url: z
+        .string()
+        .optional()
+        .describe(
+          '文章网址，支持两种格式：\n' +
+          '1. mdoc.cc 网址：https://mdoc.cc/mliev/1ms/v1.0.0/16\n' +
+          '2. manifest 中返回的 content.md API 链接，如 ' +
+          'https://mdoc.cc/openapi/organizations/mliev/documents/1ms/articles/16/content.md'
+        ),
+      orgSlug: z
+        .string()
+        .optional()
+        .describe('组织标识，如 mliev。当未提供 url 时必填。'),
+      docSlug: z
+        .string()
+        .optional()
+        .describe('文档标识，如 1ms。当未提供 url 时必填。'),
+      articleId: z
+        .string()
+        .optional()
+        .describe('文章 ID，如 16。当未提供 url 时必填。'),
+      version: z
+        .string()
+        .optional()
+        .describe('版本名称，如 v1.0.0。不指定则使用文档默认版本。'),
+    },
+  },
+  async (args) => {
+    try {
+      const client = createClientFromEnv();
+      const content = await getArticleContent(client, args);
+      return {
+        content: [{ type: 'text', text: content }],
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        content: [{ type: 'text', text: `错误: ${message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // 使用 stderr 避免干扰 stdio 传输协议
+  process.stderr.write('mdoc MCP server 已启动（stdio 模式）\n');
+}
+
+main().catch((error) => {
+  process.stderr.write(`启动失败: ${error}\n`);
+  process.exit(1);
+});

package/src/tools/get-article-content.ts

@@ -0,0 +1,66 @@
+import { MdocClient } from '../client.js';
+import { parseMdocUrl } from '../url-parser.js';
+
+export interface GetArticleContentInput {
+  url?: string;
+  orgSlug?: string;
+  docSlug?: string;
+  articleId?: string;
+  version?: string;
+}
+
+/**
+ * 获取文章的原始 Markdown 内容
+ * 对应 API: GET /openapi/organizations/:orgSlug/documents/:docSlug/articles/:articleId/content.md
+ *
+ * url 参数支持两种格式：
+ * 1. mdoc.cc 网址: https://mdoc.cc/:orgSlug/:docSlug/:version/:articleId
+ * 2. API content URL: .../openapi/organizations/.../articles/:articleId/content.md
+ */
+export async function getArticleContent(
+  client: MdocClient,
+  input: GetArticleContentInput
+): Promise<string> {
+  let orgSlug: string;
+  let docSlug: string;
+  let articleId: string;
+  let version: string | undefined = input.version;
+
+  if (input.url) {
+    const parsed = parseMdocUrl(input.url);
+
+    if (!parsed.articleId) {
+      throw new Error(
+        `无法从 URL 中解析出 articleId，请确认 URL 格式正确（如 https://mdoc.cc/org/doc/v1.0.0/16），` +
+        `或单独提供 orgSlug、docSlug 和 articleId 参数`
+      );
+    }
+
+    orgSlug = parsed.orgSlug;
+    docSlug = parsed.docSlug;
+    articleId = parsed.articleId;
+    if (!version && parsed.version) {
+      version = parsed.version;
+    }
+  } else if (input.orgSlug && input.docSlug && input.articleId) {
+    orgSlug = input.orgSlug;
+    docSlug = input.docSlug;
+    articleId = input.articleId;
+  } else {
+    throw new Error(
+      '请提供 url 参数，或同时提供 orgSlug、docSlug 和 articleId 参数'
+    );
+  }
+
+  const path =
+    `/openapi/organizations/${encodeURIComponent(orgSlug)}` +
+    `/documents/${encodeURIComponent(docSlug)}` +
+    `/articles/${encodeURIComponent(articleId)}/content.md`;
+
+  const query: Record<string, string> = {};
+  if (version) {
+    query['version'] = version;
+  }
+
+  return client.get({ path, query });
+}

package/src/tools/get-manifest.ts

@@ -0,0 +1,45 @@
+import { MdocClient } from '../client.js';
+import { parseMdocUrl } from '../url-parser.js';
+
+export interface GetManifestInput {
+  url?: string;
+  orgSlug?: string;
+  docSlug?: string;
+  version?: string;
+}
+
+/**
+ * 获取文档目录清单（Markdown 格式）
+ * 对应 API: GET /openapi/organizations/:orgSlug/documents/:docSlug/manifest
+ */
+export async function getManifest(
+  client: MdocClient,
+  input: GetManifestInput
+): Promise<string> {
+  let orgSlug: string;
+  let docSlug: string;
+  let version: string | undefined = input.version;
+
+  if (input.url) {
+    const parsed = parseMdocUrl(input.url);
+    orgSlug = parsed.orgSlug;
+    docSlug = parsed.docSlug;
+    // URL 中解析到的版本优先级低于显式传入的 version 参数
+    if (!version && parsed.version) {
+      version = parsed.version;
+    }
+  } else if (input.orgSlug && input.docSlug) {
+    orgSlug = input.orgSlug;
+    docSlug = input.docSlug;
+  } else {
+    throw new Error('请提供 url 参数，或同时提供 orgSlug 和 docSlug 参数');
+  }
+
+  const path = `/openapi/organizations/${encodeURIComponent(orgSlug)}/documents/${encodeURIComponent(docSlug)}/manifest`;
+  const query: Record<string, string> = {};
+  if (version) {
+    query['version'] = version;
+  }
+
+  return client.get({ path, query });
+}

package/src/url-parser.ts

@@ -0,0 +1,114 @@
+/**
+ * mdoc URL 解析器
+ *
+ * 支持以下格式：
+ * 1. mdoc.cc 网站 URL:
+ *    - https://mdoc.cc/:orgSlug/:docSlug
+ *    - https://mdoc.cc/:orgSlug/:docSlug/:version
+ *    - https://mdoc.cc/:orgSlug/:docSlug/:version/:articleId
+ *
+ * 2. OpenAPI content URL (从 manifest 返回的链接):
+ *    - .../openapi/organizations/:orgSlug/documents/:docSlug/articles/:articleId/content.md
+ */
+
+export interface ParsedMdocUrl {
+  orgSlug: string;
+  docSlug: string;
+  version?: string;
+  articleId?: string;
+}
+
+/**
+ * 判断字符串是否看起来像版本号（以字母开头，如 v1.0.0，或纯数字组成的版本）
+ * 版本号特征：包含字母前缀或包含点号
+ */
+function looksLikeVersion(segment: string): boolean {
+  return /^v\d/.test(segment) || /^\d+\.\d+/.test(segment);
+}
+
+/**
+ * 判断字符串是否看起来像文章 ID（纯数字）
+ */
+function looksLikeArticleId(segment: string): boolean {
+  return /^\d+$/.test(segment);
+}
+
+/**
+ * 解析 mdoc URL，提取参数
+ * @throws {Error} 如果 URL 格式无法识别
+ */
+export function parseMdocUrl(rawUrl: string): ParsedMdocUrl {
+  // 补全协议头
+  if (!rawUrl.startsWith('http://') && !rawUrl.startsWith('https://')) {
+    rawUrl = 'https://' + rawUrl;
+  }
+
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new Error(`无效的 URL 格式: ${rawUrl}`);
+  }
+
+  const pathname = url.pathname;
+  // 去掉首尾斜杠，拆分路径段
+  const segments = pathname.replace(/^\/|\/$/g, '').split('/').filter(Boolean);
+
+  // 尝试匹配 OpenAPI content URL:
+  // /openapi/organizations/:orgSlug/documents/:docSlug/articles/:articleId/content.md
+  const openapiMatch = pathname.match(
+    /\/openapi\/organizations\/([^/]+)\/documents\/([^/]+)\/articles\/([^/]+)\/content\.md/
+  );
+  if (openapiMatch) {
+    return {
+      orgSlug: openapiMatch[1],
+      docSlug: openapiMatch[2],
+      articleId: openapiMatch[3],
+    };
+  }
+
+  // 尝试匹配 OpenAPI manifest URL:
+  // /openapi/organizations/:orgSlug/documents/:docSlug/manifest
+  const manifestMatch = pathname.match(
+    /\/openapi\/organizations\/([^/]+)\/documents\/([^/]+)\/manifest/
+  );
+  if (manifestMatch) {
+    const version = url.searchParams.get('version') ?? undefined;
+    return {
+      orgSlug: manifestMatch[1],
+      docSlug: manifestMatch[2],
+      version,
+    };
+  }
+
+  // 解析 mdoc.cc 风格的网址: /:orgSlug/:docSlug[/:version[/:articleId]]
+  if (segments.length < 2) {
+    throw new Error(
+      `URL 路径段不足，期望格式: /:orgSlug/:docSlug[/:version[/:articleId]]，实际路径: ${pathname}`
+    );
+  }
+
+  const [orgSlug, docSlug, seg3, seg4] = segments;
+  let version: string | undefined;
+  let articleId: string | undefined;
+
+  if (seg3) {
+    if (looksLikeArticleId(seg3) && !seg4) {
+      // 只有纯数字且没有第四段：当做 articleId
+      articleId = seg3;
+    } else if (looksLikeVersion(seg3)) {
+      version = seg3;
+      if (seg4) {
+        articleId = seg4;
+      }
+    } else {
+      // 第三段既不像版本也不像 articleId，作为 version 兜底处理
+      version = seg3;
+      if (seg4) {
+        articleId = seg4;
+      }
+    }
+  }
+
+  return { orgSlug, docSlug, version, articleId };
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}