From 4aa83ba8601105cbb90abfbd54ae98c57e5f556e Mon Sep 17 00:00:00 2001 From: Kirigaya <1193466151@qq.com> Date: Fri, 30 May 2025 14:42:35 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20contributors=20=E5=A4=B4?= =?UTF-8?q?=E5=83=8F=E6=94=AF=E6=8C=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vitepress/config.mts | 13 ++- .vitepress/contributors.ts | 80 +++++++++++++++++++ .../theme/components/Contributors/index.vue | 48 +++++++++++ .vitepress/theme/hook/icons.ts | 11 +++ .vitepress/theme/index.mts | 3 + plugin-tutorial/concept.md | 62 +------------- .../quick-start/acquire-openmcp.md | 16 +++- preview/contributors.md | 32 +++----- preview/join.md | 16 +++- sdk-tutorial/index.md | 6 +- 10 files changed, 195 insertions(+), 92 deletions(-) create mode 100644 .vitepress/contributors.ts create mode 100644 .vitepress/theme/components/Contributors/index.vue create mode 100644 .vitepress/theme/hook/icons.ts diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 2e57445..d63fb78 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -6,13 +6,9 @@ import { InlineLinkPreviewElementTransform } from '@nolebase/vitepress-plugin-in import { ThumbnailHashImages } from '@nolebase/vitepress-plugin-thumbnail-hash/vite'; import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links'; +import { contributors } from './contributors'; import { withMermaid } from "vitepress-plugin-mermaid"; - -export const customIcons = { - share: { - svg: '' - } -} +import { customIcons } from './theme/hook/icons'; export const baseUrl = '/openmcp'; @@ -31,8 +27,11 @@ export default withMermaid({ GitChangelog({ // 填写在此处填写您的仓库链接 repoURL: () => 'https://gitea.3geeks.top/kirigaya/openmcp-document', + mapAuthors: contributors + }), + GitChangelogMarkdownSection({ + excludes: ['preview/contributors.md', 'index.md'] }), - GitChangelogMarkdownSection(), ThumbnailHashImages(), ], optimizeDeps: { diff --git a/.vitepress/contributors.ts b/.vitepress/contributors.ts new file mode 100644 index 0000000..a818f12 --- /dev/null +++ b/.vitepress/contributors.ts @@ -0,0 +1,80 @@ +interface SocialEntry { + type: 'github' | 'twitter' | 'email' | string; + link: string; +} + +interface Contributor { + /** + * The overriding display name of the contributor in default locale + */ + name?: string; + /** + * The overriding display name of the contributor in other locales if needed + */ + i18n?: Record; + /** + * The overriding GitHub, GitLab, Gitea username of the contributor + */ + username?: string; + /** + * The overriding avatar of the contributor + */ + avatar?: string; + /** + * Whether to add a link to the contributor's profile + */ + links?: string | SocialEntry[]; + /** + * More names to be recognized as the same contributor. + * + * Useful when you changed your name or email address in the past. + * + * @deprecated Use `mapByNameAliases` instead + * @see mapByNameAliases + */ + nameAliases?: string[]; + /** + * More names to be recognized as the same contributor. + * + * Useful when you changed your name or email address in the past. + */ + mapByNameAliases?: string[]; + /** + * More emails to be recognized as the same contributor. + * + * Useful when you changed your email address in the past. + * + * @deprecated Use `mapByEmailAliases` instead + * @see mapByEmailAliases + */ + emailAliases?: string[]; + /** + * More emails to be recognized as the same contributor. + * + * Useful when you changed your email address in the past. + */ + mapByEmailAliases?: string[]; +} + +export const contributors = [ + { + name: '锦恢', + nameAliases: ['LSTM-Kirigaya', 'Kirigaya'], + mapByEmailAliases: ['1193466151@qq.com'], + links: [{ type: '', link: 'https://www.zhihu.com/people/can-meng-zhong-de-che-xian' }] + }, + { + name: 'PeaceSheep', + nameAliases: ['li1553770945'], + avatar: 'https://avatars.githubusercontent.com/u/55867654?v=4', + mapByEmailAliases: ['1553770945@qq.com'], + links: [{ type: '', link: 'https://peacesheep.cn/home' }] + }, + { + name: '星弧梦影', + nameAliases: ['StarArc'], + avatar: 'https://avatars.githubusercontent.com/u/115577936?v=4', + mapByEmailAliases: ['3951001763@qq.com'], + links: [{ type: '', link: 'https://b23.tv/bqflzuJ' }] + } +] as Contributor[]; \ No newline at end of file diff --git a/.vitepress/theme/components/Contributors/index.vue b/.vitepress/theme/components/Contributors/index.vue new file mode 100644 index 0000000..346f8e2 --- /dev/null +++ b/.vitepress/theme/components/Contributors/index.vue @@ -0,0 +1,48 @@ + + + + + \ No newline at end of file diff --git a/.vitepress/theme/hook/icons.ts b/.vitepress/theme/hook/icons.ts new file mode 100644 index 0000000..083511e --- /dev/null +++ b/.vitepress/theme/hook/icons.ts @@ -0,0 +1,11 @@ +export const customIcons = { + share: { + svg: '' + }, + bilibili: { + svg: '' + }, + blog: { + svg: '' + } +} diff --git a/.vitepress/theme/index.mts b/.vitepress/theme/index.mts index 8ac3d43..e0390ac 100644 --- a/.vitepress/theme/index.mts +++ b/.vitepress/theme/index.mts @@ -9,6 +9,7 @@ import TwoSideLayout from './components/home/TwoSideLayout.vue'; import KTab from './components/KTab/index.vue'; import BiliPlayer from './components/bilibli-player/index.vue'; import KNavItem from './components/nav-item/index.vue'; +import Contributors from './components/Contributors/index.vue'; import { NolebaseGitChangelogPlugin } from '@nolebase/vitepress-plugin-git-changelog/client'; import { NolebaseInlineLinkPreviewPlugin } from '@nolebase/vitepress-plugin-inline-link-preview/client'; @@ -32,6 +33,8 @@ export default { app.component('KTab', KTab); app.component('BiliPlayer', BiliPlayer); app.component('KNavItem', KNavItem); + app.component('Contributors', Contributors); + app.component('el-collapse', ElCollapse); app.component('el-collapse-item', ElCollapseItem); app.component('el-timeline', ElTimeline); diff --git a/plugin-tutorial/concept.md b/plugin-tutorial/concept.md index 5bfe60d..894a056 100644 --- a/plugin-tutorial/concept.md +++ b/plugin-tutorial/concept.md @@ -191,69 +191,15 @@ ChatCompletionMessage( -## 开始你的第一个 mcp 服务器 +## 使用 Inspector 进行调试 -接下里就要让我们大显身手了！MCP 官方提供了几个封装好的 mcp sdk 来让我们快速开发一个 MCP 服务器。我看了一下，目前使用最爽，最简单的是 python 的 sdk，所以我就用 python 来简单演示一下了。 - -当然，如果想要使用 typescript 开发也是没问题的，typescript 的优势就是打包和部署更加简单。可以看我自用的一个模板库：[mcp-server-template](https://github.com/LSTM-Kirigaya/mcp-server-template) - -### 安装基本环境 - -首先让我们打开一个项目，安装基本的库： +Claude 原生提供的 MCP 协议可以通过官方提供的 Inspector 进行调试，对于 [[first-mcp|你的第一个 MCP]] 中的例子，可以如下进行调试，在命令行输入如下命令启动 Inspector: ```bash -pip install uv +mcp dev main.py ``` -然后进入一个目录后初始化 uv 项目并安装对应的依赖： - -```bash -mkdir -p ~/code/mcp-server -cd ~/code/mcp-server -uv init --no-workspace -uv add mcp "mcp[cli]" -``` - -创建 `server.py` - -```python -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP('锦恢的 MCP Server', version="11.45.14") - -@mcp.tool('add', '对两个数字进行实数域的加法') -def add(a: int, b: int) -> int: - return a + b - -@mcp.resource("greeting://{name}", 'greeting', '用于演示的一个资源协议') -def get_greeting(name: str) -> str: - # 访问处理 greeting://{name} 资源访问协议，然后返回 - # 此处方便起见，直接返回一个 Hello，balabala 了 - return f"Hello, {name}!" - -@mcp.prompt('translate', '进行翻译的prompt') -def translate(message: str) -> str: - return f'请将下面的话语翻译成中文：\n\n{message}' -``` - -上面的代码在装饰器的作用下非常容易读懂，`@mcp.tool`, `@mcp.resource` 和 `@mcp.prompt` 分别实现了 - -- 一个名为 add 的 tool -- 一个 greeting 协议的 resource -- 一个名为 translate 的 prompt - -> 不明白装饰器是什么小白可以看看我之前的文章[Python进阶笔记（一）装饰器实现函数/类的注册](https://zhuanlan.zhihu.com/p/350821621) -> 虽然注册器里面的第二个参数 description 不是必要的，但是仍然建议写一下，要不然大模型怎么知道你这个工具是干啥的。 - -### 使用 Inspector 进行调试 - -我们可以使用 MCP 官方提供的 Inspector 工具对上面的 server 进行调试： - -```bash -mcp dev server.py -``` - -这会启动一个前端服务器并，打开 `http://localhost:5173/` 后我们可以看到 inspector 的调试界面，先点击左侧的 `Connect` 来运行我们的 server.py 并通过 stdio 为通信管道和 web 建立通信。 +这会启动一个前端服务器，并打开 `http://localhost:5173/` 后我们可以看到 inspector 的调试界面，先点击左侧的 `Connect` 来运行我们的 server.py 并通过 stdio 为通信管道和 web 建立通信。 Fine，可以开始愉快地进行调试了，Inspector 主要给了我们三个板块，分别对应 Resources，Prompts 和 Tools。 diff --git a/plugin-tutorial/quick-start/acquire-openmcp.md b/plugin-tutorial/quick-start/acquire-openmcp.md index 207c5c9..e87da63 100644 --- a/plugin-tutorial/quick-start/acquire-openmcp.md +++ b/plugin-tutorial/quick-start/acquire-openmcp.md @@ -42,10 +42,20 @@ VLE 的插件商城页面有一个三个点的按钮，点击它后，你能看 ### 方法二：通过命令行 -如果您的 VLE 是全局安装的，会自动存在一个命令行工具，此处以 vscode 为例子（trae 的命令为 trae），打开命令行，输入 +如果您的 VLE 是全局安装的，会自动存在一个命令行工具，命令如下： -```bash +::: code-group +```bash [vscode] code --install-extension /path/to/openmcp-0.1.1.vsix ``` -/path/to/openmcp-0.1.1.vsix 代表你刚刚下载的 vsix 文件的绝对路径。这样也可以安装插件。 \ No newline at end of file +```bash [trae] +trae --install-extension /path/to/openmcp-0.1.1.vsix +``` + +```bash [cursor] +cursor --install-extension /path/to/openmcp-0.1.1.vsix +``` +::: + +`/path/to/openmcp-0.1.1.vsix` 代表你刚刚下载的 vsix 文件的绝对路径。这样也可以安装插件。 \ No newline at end of file diff --git a/preview/contributors.md b/preview/contributors.md index 282ae75..5689839 100644 --- a/preview/contributors.md +++ b/preview/contributors.md @@ -3,28 +3,27 @@ layout: page --- - - - - - - - \ No newline at end of file + \ No newline at end of file diff --git a/preview/join.md b/preview/join.md index 662a36e..d5c44af 100644 --- a/preview/join.md +++ b/preview/join.md @@ -17,4 +17,18 @@ - 为我们的项目设计新的功能，这未必一定需要阁下写代码，只是在 [MVP 需求规划](https://github.com/LSTM-Kirigaya/openmcp-client?tab=readme-ov-file#%E9%9C%80%E6%B1%82%E8%A7%84%E5%88%92) 中提出有意义的功能也是很不错的贡献。 - 通过 OpenMCP 来完成不同的 agent 开发的例子或者打磨新的开发 AI Agent 的方法论。在征得阁下本人同意后，我们将会将你的教程整合到这个网站中。 -通过向 OpenMCP 贡献以上内容或是其他，阁下将能成为 OpenMCP 的贡献者。 \ No newline at end of file +通过向 OpenMCP 贡献以上内容或是其他，阁下将能成为 OpenMCP 的贡献者。 + +## 为 openmcp 文档站点添砖加瓦 + +如果您想要为 openmcp 文档站点修复专业错误或者贡献您的例子，请 fork [openmcp-document](https://github.com/LSTM-Kirigaya/openmcp-document) 提交 PR 。 + +如果您对 github 的操作不熟悉，请 [进入 OpenMCP 开发群](https://qm.qq.com/cgi-bin/qm/qr?k=C6ZUTZvfqWoI12lWe7L93cWa1hUsuVT0&jump_from=webapi&authKey=McW6B1ogTPjPDrCyGttS890tMZGQ1KB3QLuG4aqVNRaYp4vlTSgf2c6dMcNjMuBD) 并联系管理员锦恢，请提供如下几件东西： + +- 您希望贡献的内容 +- 您的 github 账号（主页链接） +- 您的邮箱 +- 您希望展现在网站上的 ID 和 头像 +- 您希望关联的网站链接（比如b站，知乎，个人网站什么的） + +完成添加后，您就可以向 [openmcp-document](https://github.com/LSTM-Kirigaya/openmcp-document) 提交 PR 了。 \ No newline at end of file diff --git a/sdk-tutorial/index.md b/sdk-tutorial/index.md index a4493ca..a918fa8 100644 --- a/sdk-tutorial/index.md +++ b/sdk-tutorial/index.md @@ -14,15 +14,15 @@ OpenMCP Client 提供了一体化的 MCP 调试解决方案，这很好，但是 ## 安装 ::: code-group -```[npm] +```bash [npm] npm install openmcp-sdk ``` -```[yarn] +```bash [yarn] yarn add openmcp-sdk ``` -```[pnpm] +```bash [pnpm] pnpm add openmcp-sdk ``` :::