MCP Anki Generator

MCP研究项目

免责声明： 此项目仅供教育用途。其主要目标是展示和理解消息控制协议（MCP）的基本原理。它并非旨在用于生产环境，除了作为学习练习外，不具有任何实际应用价值。

概述

这个项目实现了一个使用（某种技术或框架）的简单服务器 FastMCP 框架用于说明如何使用远程调用程序（RCP）使不同组件之间相互通信。服务器设计为与歌词协同工作，并提供了处理和操作文本数据的工具。

执行项目

安装紫外线灯

UV 是一个基于 Rust 的包管理器，它不像 poetry 那样糟糕。你可以使用以下命令在 Linux 或 macOS 上安装它：

wget -qO- https://astral.sh/uv/install.sh | sh

如果你使用的是Windows系统，你还有时间来悔改你的“罪行”，或者你可以使用以下命令：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

虽然不建议使用，但你也可以使用 pipx：

pipx install uv

启动服务器

让其运行起来最简单的方法是作为网络服务器：

uv run src/main.py # install and run the server

这将启动 FastMCP 配备有……的服务器 streamable-http 传输，使其准备好接受请求。

与VSCode一起使用

运行项目后，您应该能够使用Copilot Chat来与它互动。

ctrl | cmd + shift + p

你可以使用 # 选择资源和工具。由于某种原因，这个库提供的资源无法正常工作，因此您必须手动选择输入。

通常，人工智能应该能够根据上下文自行选择合适的工具，然而，GPT-4o已被证明非常愚蠢，因此你可能需要手动指示它使用正确的工具。可用的工具包括：

• normalize_text移除括号内容、标点符号、多余的换行和多余的空格。
• split_unique_word将文本拆分为唯一的、首字母大写的单词，忽略标点符号（撇号除外）。
• split_unique_sentences按换行符拆分歌曲歌词，去除重复项（忽略大小写/空格），并将每行的第一个字符大写。
• save_csv_to_file以“原文，译文”的格式保存到CSV文件中。

为了获得更好的结果，请按照上述顺序操作。您可能还需要在额外的步骤中翻译句子或单词。

解决VSCode中的问题

确保您使用的是最新版本的VSCode。即使您当前的版本支持MCP服务器，它也可能与（某些功能或环境）不完全兼容 StreamableHTTP所以要多加留意。

如果您需要重启或强制启动，请前往 .vscode/mcp.json在第三行的“local”上方，你会看到一些选项。如果你看不到这些选项，那么你应该考虑升级你的版本，或者停止使用仿制品，安装正版的VSCode（我这话是说给VSCodium用户听的）。

它是如何运作的

该项目的核心是MCP服务器，它负责协调客户端、服务器本身以及AI层之间的通信。这种通信是通过一个……进行的 streamable-http 传输，使得系统中不同的部分能够像调用本地函数一样远程调用函数。

架构层

该系统由三个主要的概念层组成：

1. 服务器层主要应用程序，定义于 server.py，从而创造出一个 FastMCP 例子 这一层负责管理和提供可远程访问的“资源”和“工具”。

1. 客户端层任何能够向服务器端点发送HTTP请求的应用程序都可以。客户端发起请求以调用服务器上的过程，例如获取歌词或请求AI执行任务。我建议使用Claude Desktop或配备MCP的VSCode。

1. AI层在MCP框架内的智能能够通过串联对已注册（功能/服务）的调用来理解和执行复杂任务 @mcp.tool() 功能。例如，客户可以要求AI“将一首歌的歌词进行标准化并拆分”，然后AI会使用 normalize_text 并且 split_unique_word 完成这一任务的工具。

由于GPT-5与我的工具配合不佳，我一直在使用GPT-4o。请注意，并非所有AI都支持MCP客户端，因此建议使用它们的最新版本，这样应该就没问题了。

远程调用过程（RCP）

RCP（运行时组件协议）是允许各层之间进行通信的机制。在这个项目中，它是通过装饰器来实现的：

• @mcp.resource这个装饰器将一个函数暴露为数据资源。在 services/resources.py，的 retrieve_lyrics 该功能已公开，允许客户端通过歌曲名称获取歌词（例如。， file://src/assets/lyrics/100_messagi)。

• @mcp.tool()这个装饰器将一个函数注册为AI层可以使用的工具。其中的函数 services/tools.py (like normalize_text， split_unique_sentences（等）是这些工具的例子。人工智能可以将这些构建模块组合起来，以执行客户请求的任务。

如果你想真正理解它是如何工作的，不妨花些时间使用Ollama并实现你自己的协议。这样你也会更好地了解模型的局限性。