diff --git a/.vitepress/config.mts b/.vitepress/config.mts index f5c2a99..2e57445 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -175,6 +175,8 @@ export default withMermaid({ { text: '快速开始', link: '/plugin-tutorial/quick-start' }, { text: '安装 OpenMCP', link: '/plugin-tutorial/quick-start/acquire-openmcp' }, { text: '你的第一个 MCP', link: '/plugin-tutorial/quick-start/first-mcp' }, + { text: '快速调试 MCP', link: '/plugin-tutorial/quick-start/quick-debug' }, + { text: '扔进大模型里面测测好坏！', link: '/plugin-tutorial/quick-start/put-into-llm' }, ] }, { diff --git a/.vitepress/theme/index.mts b/.vitepress/theme/index.mts index 1267431..8ac3d43 100644 --- a/.vitepress/theme/index.mts +++ b/.vitepress/theme/index.mts @@ -13,7 +13,7 @@ import KNavItem from './components/nav-item/index.vue'; import { NolebaseGitChangelogPlugin } from '@nolebase/vitepress-plugin-git-changelog/client'; import { NolebaseInlineLinkPreviewPlugin } from '@nolebase/vitepress-plugin-inline-link-preview/client'; -import { ElCollapse, ElCollapseItem } from 'element-plus'; +import { ElCollapse, ElCollapseItem, ElTimeline, ElTimelineItem } from 'element-plus'; import './css/style.css'; import './css/iconfont.css'; @@ -34,6 +34,9 @@ export default { app.component('KNavItem', KNavItem); app.component('el-collapse', ElCollapse); app.component('el-collapse-item', ElCollapseItem); + app.component('el-timeline', ElTimeline); + app.component('el-timeline-item', ElTimelineItem); + app.use(NolebaseGitChangelogPlugin); app.use(NolebaseInlineLinkPreviewPlugin); } diff --git a/plugin-tutorial/quick-start/index.md b/plugin-tutorial/quick-start/index.md index e69de29..c09f987 100644 --- a/plugin-tutorial/quick-start/index.md +++ b/plugin-tutorial/quick-start/index.md @@ -0,0 +1,11 @@ +# 快速开始 + +1. [[acquire-openmcp|获取 OpenMCP]] + +2. [[first-mcp|你的第一个 MCP]] +3. [[quick-debug|快速调试 MCP]] +4. [[put-into-llm|扔进大模型里面测测好坏！]] + + +
+
diff --git a/plugin-tutorial/quick-start/put-into-llm.md b/plugin-tutorial/quick-start/put-into-llm.md new file mode 100644 index 0000000..d6b2218 --- /dev/null +++ b/plugin-tutorial/quick-start/put-into-llm.md @@ -0,0 +1,2 @@ +# 扔进大模型里面测测好坏！ + diff --git a/plugin-tutorial/quick-start/quick-debug.md b/plugin-tutorial/quick-start/quick-debug.md new file mode 100644 index 0000000..45cbf58 --- /dev/null +++ b/plugin-tutorial/quick-start/quick-debug.md @@ -0,0 +1,2 @@ +# 快速调试 MCP + diff --git a/plugin-tutorial/usage/connect-mcp.md b/plugin-tutorial/usage/connect-mcp.md index de6e0b4..569c793 100644 --- a/plugin-tutorial/usage/connect-mcp.md +++ b/plugin-tutorial/usage/connect-mcp.md @@ -6,83 +6,47 @@ MCP 客户端是指能够通过 MCP 协议进行通信的大模型对话客户端，通常是一个运行在本地的应用程序（因为网页没有文件IO的权限）。它的产品形式目前几乎都是聊天机器人的形式，类似于你在网页使用的 chat.deepseek.com 或者 chat.openai.com ::: -首先，打开你的 VLE，在 [[../quick-start/acquire-openmcp|获取 OpenMCP]] 中完成 OpenMCP 的安装后，我们先用 python 创建一个最简单的 mcp 服务器，来测试 mcp 客户端的连接。 +首先，打开你的 VLE，在 [[acquire-openmcp|获取 OpenMCP]] 中完成 OpenMCP 的安装后，我们先用 python 创建一个最简单的 mcp 服务器，来测试 mcp 客户端的连接。 ## 使用 OpenMCP 一键连接 -如上，我们申明了三个函数，用作 mcp 的 tool，resource 和 prompt。在 OpenMCP 中启动它们非常简单，点击右上角的 OpenMCP 图标即可连接： +在 [[first-mcp|你的第一个 MCP]] 这个例子中，我们申明了三个函数，用作 mcp 的 tool，resource 和 prompt。在 OpenMCP 中启动它们非常简单，点击右上角的 OpenMCP 图标即可连接： ![](./images/connect-simple.png) -初次使用 OpenMCP，会出现引导界面，还希望阁下可以耐心看完。 - -![](./images/guide.png) 如果登录完成后，如图显示连接成功，则代表当前已经成功启动并连接 mcp 服务器。 ![](./images/connect-success.png) -恭喜您，万事开头难，您已经完成了最难的 mcp 连接！ +## STDIO 连接的启动 -## 附录：关于 uv 启动 mcp 你必须知道的 +对于 STDIO 为连接选项的开发方案，我们提供了一键式的快速启动，您不需要额外启动 mcp 的进程。OpenMCP 会自动连接和销毁。 -OpenMCP 已经帮你做好了很多事情，但是使用 uv 启动 mcp 服务器其实是不只一种方法的，了解更加底层的原理有助于您以不变应万变。因为 OpenMCP 对于 python 项目默认运行 `uv run mcp run main.py` 来启动 mcp 服务器，但是 GitHub 上的部分项目无法这么启动。 +目前支持的编程语言和它们对应的启动参数为： -先了解一下正常的如下的代码应该如何通过命令行启动 mcp 吧！ +|语言|连接参数|启动目录| +|:-|:-|:-| +|python|uv run mcp run $\{file\} | 往上追溯，第一个找到的 pyproject.toml 的目录| +|nodejs|node $\{file\}| 往上追溯，第一个找到的 package.json 的目录| +|go|go run $\{file\}| 往上追溯，第一个找到的 go.mod 的目录| + +## SSE & HTTP 连接的启动 + +对于 SSE 和 HTTP 这种远程连接的方式，由于我们并不知道您到底在哪个端口启动的服务器（因为你有可能把启动的 host 和 port 写在不可见的配置文件里或者写在环境变量里），因此，对于远程连接的情况，我们不支持自动创建服务器，您需要手动配置启动选项。 + +点击 VLE 左侧插件栏目的 OpenMCP，在 「MCP 连接（工作区）」 视图中，点击 + ，就可以创建一个新的连接。 + +![](./images/add-connection.png) -```python -from mcp.server.fastmcp import FastMCP -mcp = FastMCP('锦恢的 MCP Server', version="11.45.14") +然后根据你的实际启动情况选择启动选项即可。 -@mcp.tool( - name='add', - description='对两个数字进行实数域的加法' -) -def add(a: int, b: int) -> int: - return a + b +:::info +需要注意的是 -@mcp.resource( - uri="greeting://{name}", - name='greeting', - description='用于演示的一个资源协议' -) -def get_greeting(name: str) -> str: - return f"Hello, {name}!" - -@mcp.prompt( - name='translate', - description='进行翻译的prompt' -) -def translate(message: str) -> str: - return f'请将下面的话语翻译成中文：\n\n{message}' -``` - -### 方法一：使用 mcp-cli - -mcp 本身提供了脚手架，可以直接启动一段被申明的 python 代码，作为一个 mcp 服务器。使用如下代码运行它： - -```bash -uv run mcp run main.py -``` - -### 方法二：在代码中显式启动 - -你也可以在代码中显式启动 mcp 服务器，在 `main.py` 的结尾添加： - -```python -if __name__ == '__main__': - mcp.run() -``` - -然后运行如下代码即可启动 mcp 服务器： - -```bash -uv run main.py -``` - -:::warning -请不要运行 python main.py，因为 uv run 会使用当前虚拟环境的库，这些库在外部 python 看来是不可见的。也不要在没有使用 `mcp.run()` 启动代码的情况下就直接使用 mcp run main.py，我们之前的代码只是申明了函数，并没有实际上执行任何功能。 +如果是以 SSE 启动，那么输入的链接必须以 /sse 结尾，比如 http://localhost:8001/sse +如果是以 Streamable Http 启动，那么输入的链接必须以 /stream 结尾，比如 http://localhost:8001/stream ::: diff --git a/plugin-tutorial/usage/images/add-connection.png b/plugin-tutorial/usage/images/add-connection.png new file mode 100644 index 0000000..4b574be Binary files /dev/null and b/plugin-tutorial/usage/images/add-connection.png differ