NetStone.MCP

NetStone.MCP

一个使用 .NET 8 构建的 Final Fantasy XIV Model Context Protocol (MCP) 服务。

NetStone.MCP 可将大模型客户端（Claude Desktop、Cursor、ChatGPT、自定义 Discord 机器人和自主 Agent）直接连接到 FFXIV 游戏数据，包括官方 Lodestone 角色和部队数据、PaissaDB 实时房屋可购买情况、FFXIV Collect 收藏品和坐骑、XIVAPI v2 配方，以及中文社区传说和 Wiki 数据库。

支持 Stdio（本地进程）和 HTTP / SSE（远程服务）两种传输模式。

---

数据源

来源	集成方式	提供的功能
NetStone	Lodestone 抓取器	角色资料、职业/特职等级、坐骑数量、自由部队、通讯贝
PaissaHouse	PaissaDB API	实时可购买的房屋地块、尺寸、价格和抽奖登记信息
FFXIV Collect	Collect API	坐骑、宠物、表情动作、发型、管弦乐琴谱、青魔法、陆行鸟装甲、时尚配饰、成就
Huiji Wiki (灰机Wiki)	MediaWiki API	中文传说、任务、迷宫/团队副本、首领机制、物品和译文
XIVAPI v2	XIVAPI REST	物品搜索、制作配方和材料明细
FFXIV Lodestone News	News API	官方维护计划、主题和新闻文章
Thaliak	补丁追踪器	最新游戏客户端和资料片版本号
Square Enix Store	商店抓取器	在线商店分类、新品和折扣商品

---

快速开始

1. Claude Desktop（Stdio 模式）

将 NetStone.MCP 添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "netstone-mcp": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:\\path\\to\\NetStoneMCP\\src\\NetStoneMCP.csproj",
        "--no-build"
      ]
    }
  }
}

2. HTTP / SSE 模式（Cursor、VS Code、远程客户端）

使用 SSE 传输方式启动 NetStone.MCP：

export TransportType=SSE
dotnet run --project src/NetStoneMCP.csproj

MCP SSE 端点将监听：

http://localhost:5000/sse

3. Docker Compose（服务 + Discord 机器人）

使用一条命令运行 NetStoneMCP 和示例 Discord 机器人：

cp .env.example .env
# Edit .env and supply OPENAI_API_KEY and DISCORD_BOT_KEY
docker compose up -d --build

---

可用的 MCP 工具

角色与社交（Lodestone）

工具	描述
get_player_info	根据名称和世界查询角色资料（等级、头像、大国防联军、自由部队、个人简介）。
get_player_class_job	查询角色所有战斗职业、制作职业和采集职业的等级。
get_character_mount_count	查询角色已解锁的坐骑总数。
get_fc_information	查询自由部队资料、等级、口号和生效中的增益效果。
get_fc_members	查询自由部队完整成员名单。
get_crossworld_linkshell_information	根据名称和数据中心查询跨界通讯贝资料及成员名单。
get_linkshell_information	根据名称和世界查询通讯贝资料及成员名单。

收藏品与可解锁内容（FFXIV Collect）

工具	描述
get_ffxiv_mount	查询坐骑获取来源、乘坐人数、补丁和是否可交易。
get_ffxiv_minion	查询宠物掉落地点、获取来源和说明。
get_ffxiv_emote	查询表情动作解锁指令（/emote）、来源和补丁。
get_ffxiv_hairstyle	查询现代美学发型的获取方式（MGP、PvP、博兹雅等）。
get_ffxiv_orchestrion	查询管弦乐琴谱编号、类别和掉落来源。
get_ffxiv_blue_mage_spell	查询青魔法技能的学习条件（狂欢、迷宫、野外怪物）。
get_ffxiv_barding	查询陆行鸟装甲的来源及是否可交易。
get_ffxiv_fashion	查询时尚配饰（翅膀、伞/阳伞、眼镜、背包）。
get_ffxiv_achievement	查询成就点数、条件和奖励（头衔、坐骑、物品）。
search_ffxiv_collectable	跨所有收藏品类型进行多类别收藏品查询。

世界观与 Wiki 数据库（Huiji Wiki / 灰機Wiki / 灰机Wiki）

工具	描述
search_huiji_wiki	搜索中文 FFXIV 数据库中的任务、地下城、世界观、NPC 和机制。支持自然语言查询（例如“幫我用灰機查...”）。
get_huiji_wiki_summary	获取主题或页面的简明摘要和介绍。
get_huiji_wiki_page_section	获取完整章节内容（例如攻略指南、背景世界观、掉落列表）。

道具与制作（XIVAPI v2）

工具	描述
get_item_by_name	按名称查找道具，并获取道具 ID 和元数据。
get_item_recipes	获取制作配方详情、所需制作等级和材料列表。

房屋与服务器状态

工具	描述
get_house_information	获取可购买的房屋地块、尺寸、价格和彩票信息（PaissaDB）。
get_data_center	列出所有官方数据中心。
get_world	列出所有世界及其所属数据中心。
get_ffxiv_cht_lock_server	获取繁体中文服务器当前的角色创建限制状态。

新闻、版本与在线商店

工具	描述
ffxiv_get_current_maintenance	获取当前和即将进行的维护时间表及说明。
ffxiv_get_topics	获取来自 Lodestone 的最新官方新闻和主题。
ffxiv_get_post	根据 ID 获取特定 Lodestone 帖子的全文。
get_ffxiv_latest_versions	获取基础游戏和资料片（boot、ex1–ex5）的最新补丁版本字符串。
get_ffxiv_latest_chn_text_patch	获取最新社区中文本地化补丁（漢化 / 中文化補丁）的发布信息和下载链接。
get_store_categories	获取 FFXIV 在线商店中的商品类别。
get_store_new_product	获取在线商店中新上架的商品。
get_store_on_sale_product	获取在线商店中当前打折的商品。
get_store_product	按类别名称筛选商店商品。

---

示例应用

可在 sample/ 目录中找到开箱即用的示例客户端：

1. Discord 机器人（sample/NetStoneDiscordBot）

一款由 OpenAI Function Calling 和 NetStoneMCP 工具驱动、具有频道上下文记忆的 Discord 机器人。

交互式选项澄清

当用户提示词含糊或有多个可能目标时（例如询问 “查巴哈”，可能指巴哈姆特大区服务器、大迷宫巴哈姆特或蛮神世界观），AI 会调用 ask_user_options 工具，显示可交互的 Discord 按钮。用户只需点击一个选项，即可继续执行确切查询，无需猜测。

频道记忆与延长

为每个 Discord 频道维护独立的对话上下文。记忆设置为 10 分钟后过期时，会显示一个可交互的 延長記憶 10 分鐘 按钮，用户可通过该按钮将会话时长延长至最多 1 小时。

角色扮演人设切换（!skill）

可随时在聊天中切换角色人设。人设以 Markdown 模板形式定义在 sample/NetStoneDiscordBot/Skills/ 中：

人设命令	角色	描述与别名
!skill 雅修特拉	雅·修特拉（Y'shtola）	拂晓大魔女，知性优雅、略带毒舌，是以太学大师（永远的 23 岁）。别名：yshtola、貓娘、魔女
!skill 愛梅特賽爾克	爱梅特赛尔克（Emet-Selch）	厌世傲慢却深情博学的原初之人（“记住我们曾经活过”）。别名：emetselch、愛梅、哈迪斯
!skill 古拉哈提亞	古·拉哈·提亚（G'raha Tia）	热情坦率、憧憬英雄的拂晓贤人，喜爱美食与冒险。别名：grahatia、水晶公、貓男
!skill 塔塔露	塔塔露（Tataru）	拂晓财政总管与裁缝神匠，满口“是也！”，寸步不让。别名：tataru、大掌櫃、拉拉肥
!skill 阿莉塞	阿莉塞（Alisaie）	率真好胜、傲娇热血的赤魔少女，吐槽阿尔菲诺时毫不留情。别名：alisaie、赤魔
!skill 艾斯蒂尼安	艾斯蒂尼安（Estinien）	孤高寡言的苍天龙骑，实力超群但金钱观薄弱。别名：estinien、大師兄、龍騎
!skill 猴子	猴子（Monkey）	机灵幽默的香蕉猴子。别名：monkey
!skill off / default	默认模式	客观中立的专业 FFXIV 知识库助手。

2. WPF 桌面客户端（sample/NetStoneClient）

一款使用 WPF 构建的桌面聊天应用，集成了 OpenAI 聊天补全功能和 NetStoneMCP 工具调用。

---

配置和环境变量

变量	默认值	描述
TransportType / TRANSPORT_TYPE	Stdio	MCP 传输模式：Stdio（标准输入/输出）或 SSE（HTTP 服务器发送事件）。
NETSTONE_SSE_URL	http://localhost:5000/sse	在 SSE 模式下运行时，客户端/机器人使用的端点。
OPENAI_API_KEY	(None)	OpenAI API 密钥（Discord Bot 和 WPF Client 必需）。
OPENAI_MODEL	gpt-5.1	示例客户端使用的大模型。
DISCORD_BOT_KEY	(None)	Discord Bot 令牌（Discord Bot 必需）。

---

截图

用于消除模糊查询歧义的 Discord Bot 交互式澄清按钮

Claude Desktop 通过 Stdio MCP 查询 Lodestone 数据

WPF 桌面客户端调用 NetStoneMCP 工具

交互式控制台客户端

---

开发

# Build the entire solution
dotnet build src/NetStoneMCP.sln

# Run all automated tests
dotnet test src/NetStoneMCP.sln