AnyShare MCP 集成开发使用指南

AnyShare MCP集成开发使用文档

目标：帮助第一次接触 MCP 的同学快速上手。
数据来源：本机 MCP 工具描述 + 我在当前环境做的真实调用结果（2026-04-16）。

---

1. Cursor 配置 MCP（先做）

先在 Cursor 里把 MCP 服务连上，再开始调用工具。推荐直接在 mcp.json 配置远程 streamableHttp：

{
  "mcpServers": {
    "asmcp": {
      "type": "streamableHttp",
      "url": "https://anyshare.aishu.cn/asmcp",
      "headers": {
        "Authorization": "<token>"
      }
    }
  }
}

参数说明（小白版）：

• mcpServers：所有 MCP 服务的集合；
• asmcp：服务名称，可自定义（建议保持 asmcp 方便识别）；
• type：连接类型，远程服务使用 streamableHttp；
• url：AnyShare MCP 服务地址；
• headers.Authorization：鉴权头Bearer Token。

操作建议：

1. 初次配置先填一个可用 token，确保服务能连通；
2. token 过期后只需要更新 headers.Authorization；
3. 如果接入方具备自动鉴权能力，可交由系统自动刷新 token。

---

2. 在 Cursor 中实际怎么用（看图操作）

步骤 1：打开 MCP 服务入口

进入 Cursor 的 Settings > Tools & MCPs，点击 New MCP Server（或 Add a Custom MCP Server）来新建一个 MCP 服务。

步骤 2：填写 mcp.json 配置

在新建流程里打开/填写 mcp.json，按下图方式配置远程 streamableHttp（type、url、headers.Authorization，即 <token>）。配置保存后，该 MCP 服务会出现在 Tools & MCPs 列表里。

步骤 3：在对话里先确认可用工具

建议先让 Agent 列出当前可用 MCP 工具，确认服务连接成功、工具可见，再进入具体业务调用。

步骤 4：开始业务调用并产出文档

连接成功后，可直接在对话中调用认证、文档库、检索等工具，这里我让它一个个调用了mcp服务支持的工具并生成了这个使用手册的草稿。

3. 简单尝试（3 分钟上手）

1. 先拿 token（推荐 auth_access_token_by_account）。
2. 再用文档库工具确认你看得到哪些库（doc_lib_owned / doc_lib_list）。
3. 再做文件检索（file_search / intelli_all_search / kc_search_wiki_docs）。
4. 需要分享链接时用 file_share_path（会自动补建实名链接）。

---

4. 认证与令牌（最重要）

推荐流程 A（最简单）

• 工具：auth_access_token_by_account
• 用途：用应用 client_id/client_secret + 用户账号，直接拿用户 token

真实输入：

{
  "account": "z1",
  "client_id": "72deafac-a70b-453d-9bbc-1215c323c009",
  "client_secret": "111111"
}

真实输出（已脱敏）：

{
  "access_token": "ory_at_***",
  "expires_in": 3600,
  "scope": "all",
  "token_type": "bearer"
}

推荐流程 B（OAuth2 标准链路）

1. auth_oauth2_app_token：拿应用 token（成功）
2. auth_oauth2_user_assertion：拿用户 assertion（成功）
3. auth_oauth2_user_token：assertion 换用户 token（用真实 assertion 会成功；我用假 assertion 实测报 400）

auth_get_user_token 是以上 3 步的一站式封装，实测成功。

---

5. 各工具清单（按模块）

说明：

• 已实测：我在当前环境跑过；
• 成功/失败：失败不代表工具坏，很多是“参数刻意造错”或“服务端未开放”；

模块	工具	作用	实测结果
认证	auth_access_token_by_account	账号直取用户 token	成功
认证	auth_oauth2_app_token	取应用 token	成功
认证	auth_oauth2_user_assertion	取用户 assertion	成功
认证	auth_oauth2_user_token	assertion 换用户 token	失败（故意传假 assertion）
认证	auth_get_user_token	一站式拿用户 token	成功
认证	auth_pwd_login	账号密码登录（需 RSA 密文密码）	失败（明文密码会报参数不合法）
文档库	doc_lib_owned	我管理的文档库列表	成功
文档库	doc_lib_list	可见文档库列表	成功
文档库	doc_lib_user_quota	用户配额	成功
文档库	doc_lib_quota	指定文档库配额	失败（传参格式不合法）
目录/文件	folder_sub_objects	分页列举子目录文件	成功
目录/文件	file_convert_path	gns 转 namepath	成功
目录/文件	dir_create	创建目录	失败（故意传不存在父目录）
搜索	file_search	文件全文/属性检索	成功
搜索	intelli_all_search	智能一体化搜索	成功
搜索	kc_search_wiki_docs	wiki 搜索	成功
搜索	search_both	同时跑 wiki + all_search	成功
搜索	retrieval	切片召回	成功（返回空列表）
搜索	ecosearch_slice_search	ECOSearch 切片召回	成功（返回空）
搜索	slicefetch	拉取切片上下文	成功（空结果）
搜索	rerank_hybrid	对候选记录重排	成功（无命中）
分享	file_sharedlink_realname	查询已有实名链接	失败（无记录时提示空数组）
分享	file_sharedlink_realname_create	创建实名链接	成功
分享	sharedlink_parse	解析 shared link	失败（故意传无效 link_id）
分享	file_share_path	生成“链接+文件名+路径”展示信息	成功
对话	chat_send	向 Bot 发问	成功
对话	smart_assistant	智能助手封装问答	成功（本次返回空答案）
上传下载	file_osbeginupload	初始化上传，拿 PUT URL	成功
上传下载	file_osendupload	上传完成确认	失败（故意传假 rev/docid）
上传下载	file_osdownload	获取下载协议信息	失败（故意传假 docid）

---

6. 最常用 8 个工具（含真实样例）

6.1 doc_lib_owned

输入：

{"access_token":"ory_at_***"}

输出（节选）：

{
  "items": [
    {"id":"gns://393ECF...","name":"z1","type":"user_doc_lib"},
    {"id":"gns://EA5E27...","name":"qa数据","type":"department_doc_lib"}
  ]
}

6.2 folder_sub_objects

输入：

{"access_token":"ory_at_***","id":"gns://393ECF...","limit":5}

输出（节选）：

{
  "doc_lib":{"id":"gns://393ECF...","name":"z1","type":"user_doc_lib"},
  "dirs":[{"name":"临时区文件夹","id":"gns://393ECF.../B1E6C100..."}],
  "files":[],
  "next_marker":""
}

6.3 file_search

输入：

{"access_token":"ory_at_***","type":"all","keyword":"测试","rows":2,"start":0}

输出（节选）：

{
  "hits": 1000,
  "next": 2,
  "files": [
    {"basename":"测试","extension":".docx","score":90.08},
    {"basename":"测试","extension":".docx","score":88.41}
  ]
}

6.4 kc_search_wiki_docs

输入：

{"access_token":"ory_at_***","keyword":"测试","rows":5,"start":0}

输出（节选）：

{
  "msg":"success",
  "data":{"hits":116,"next":5}
}

6.5 file_sharedlink_realname_create

输入：

{"access_token":"ory_at_***","item":{"id":"gns://393ECF...","type":"folder"}}

输出：

{
  "id":"ARB005EDB9CE5D4144AC20D141B98F56F0",
  "link_url":"https://nginx-ingress-class-443/link/ARB005EDB9CE5D4144AC20D141B98F56F0",
  "type":"realname"
}

6.6 file_share_path

输入：

{"access_token":"ory_at_***","docid":"gns://393ECF...","item_type":"folder"}

输出：

{
  "file_name":"z1",
  "file_path_anyshare":"AnyShare://z1",
  "link_url":"https://nginx-ingress-class-443/link/ARABECC...",
  "text":"https://...\\n文件名：z1\\n文件路径：AnyShare://z1"
}

6.7 chat_send

输入：

{"access_token":"ory_at_***","bot_id":"smart_assistant","query":"你好，返回一句测试成功"}

输出（节选）：

{
  "status":"completed",
  "bot_name":"知识助手",
  "answer":"你好，测试成功。我是企业内部知识助手..."
}

6.8 file_osbeginupload

输入：

{"access_token":"ory_at_***","docid":"gns://393ECF...","length":5,"name":"mcp-test.txt"}

输出（节选）：

{
  "docid":"gns://393ECF.../15CBE0B6...",
  "rev":"17DBB0627A5A44FD98612F11FC8F12CF",
  "authrequest":["PUT","https://...","Authorization: AWS ...","Content-Type: application/octet-stream"]
}

---

7. 容易踩坑（必看）

• auth_pwd_login 的 password 不是明文，必须是 RSA 加密 + base64。
• 多数工具都支持传 access_token，建议显式传，避免隐式头部不一致。
• doc_lib_quota 的 doc_lib_id 通常不能直接塞 gns://... 全路径（当前实测 400），要按服务端要求格式。
• file_sharedlink_realname 只查“已有”链接，不会自动创建；空数组会报错文本。
• file_share_path 会在没有链接时自动创建链接（有副作用）。
• file_osbeginupload 只是拿上传协议，不是文件已上传；要真正完成还需“对象存储 PUT + file_osendupload”。

---