神岛数据统计 MCP 接口定义

基于 Model Context Protocol (MCP) 规范构建的远程服务，专用于获取神岛平台的用户档案、地理信息资产，以及详细的运营统计数据。

核心能力集

• 非授权访问: 允许对基础信息（如用户档案摘要、内容元数据、社区反馈列表）进行无需凭证的查询。
• 授权访问: 针对敏感或高频数据（如用户反馈详情、详尽的运营指标）要求提供有效的身份验证令牌 (Token)。
• 地理空间分析: 提供深度地图数据解析，涵盖玩家分布、长期留存趋势、以及活动模式分析。
• 架构清晰: 采用模块化设计原则，确保代码库的健壮性、可维护性与未来的功能扩展潜力。
• 跨平台适配: 优化了对各种客户端环境（Web 浏览器、命令行工具等）的对接支持。

可用工具集

基础/公开端点 (Public Endpoints)

方法名称	职能描述	必需输入参数
fetchUserProfile	检索特定用户档案详情	userId
retrieveMapMetadata	获取地图内容的详细规格	mapId
queryContentFeedback	拉取地图内容的评论集合	contentId, limit, offset, orderBy, contentType
fetchMapPublicationDetails	索取地图的发布及版本信息	contentId, limit, offset
enumerateUserMaps	列出指定创作者所拥有的地图资源	userId, limit, offset
listUserAssets	检索用户已上传的模型清单	userId, limit, offset
fetchUserFavorites	查阅用户收藏夹的条目	userId, limit, offset, contentType
getRecentPlayHistory	获取用户的近期游玩记录	userId, limit, offset
discoverFollowerNetwork	提取用户的关注者群体列表	userId, limit, offset
accessUserContactList	获取用户的好友关系网络	userId, limit, offset
scanFollowingDirectory	检索用户当前关注的目标列表	userId, limit, offset
searchContentByTerm	执行地图或模型的关键词检索	keyword, limit, offset, orderBy

授权访问端点 (Authenticated Endpoints)

方法名称	职能描述	必需输入参数
retrieveUserFeedbackLog	获取当前用户提交的所有反馈记录	offset, limit, token, userAgent
getAffirmationRecords	提取用户点赞或支持的操作记录	offset, limit, token, userAgent
fetchSystemNotifications	调取用户的系统级通知信息	offset, limit, token, userAgent
aggregateMapMetrics	汇总特定时间窗口内的地图总体表现数据	startTime, endTime, token, userAgent
detailMapPlayerStatistics	分析特定地图的玩家参与度统计	startTime, endTime, mapId, token, userAgent
calculatePlayerLongevity	评估特定地图的用户留存曲线	startTime, endTime, mapId, token, userAgent
analyzePlayerInteraction	深入探究玩家在地图上的行为模式	startTime, endTime, mapId, token, userAgent

客户端集成范例

公开接口调用示例 (JavaScript/TypeScript)

typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// 建立传输通道配置 const transport = new StdioClientTransport({ command: "npx", args: ["-y", "@smithery/cli@latest", "run", "@dao3fun/statistics-mcp"], });

// 实例化MCP客户端 const client = new Client( { name: "dao3-client", version: "1.0.0" }, { capabilities: { tools: {} } } );

// 建立连接 await client.connect(transport);

// 提取用户档案 (公开) const userProfile = await client.callTool({ name: "fetchUserProfile", arguments: { userId: "83354" }, });

// 获取地图元数据 (公开) const mapInfo = await client.callTool({ name: "retrieveMapMetadata", arguments: { mapId: "100131463" }, });

console.log(JSON.parse(userProfile.content[0].text));

授权接口调用示例 (JavaScript/TypeScript)

typescript // 认证凭证 const secureToken = "YOUR_TOKEN"; const clientSignature = "Mozilla/5.0 ...";

// 汇总地图运营数据 (需授权) const aggregatedMetrics = await client.callTool({ name: "aggregateMapMetrics", arguments: { startTime: "2025-03-29", endTime: "2025-04-04", token: secureToken, userAgent: clientSignature, }, });

// 评估地图玩家粘性 (需授权) const longevityData = await client.callTool({ name: "calculatePlayerLongevity", arguments: { startTime: "2025-03-29", endTime: "2025-04-04", mapId: "100131463", token: secureToken, userAgent: clientSignature, }, });

// 结果解析 const metricsResult = JSON.parse(aggregatedMetrics.content[0].text);

代码仓库组织结构

├── index.ts # 服务启动与核心逻辑文件 ├── src/ # 核心源代码区域 │ ├── types/ # 接口与数据结构定义 │ │ └── index.ts # 共享类型定义文件 │ ├── utils/ # 辅助函数模块 │ │ └── api.ts # 底层网络交互封装 │ └── tools/ # MCP工具函数实现 │ ├── publicTools.ts # 无需认证的工具实现 │ └── auth/ # 授权访问工具集 │ ├── index.ts │ ├── auth_msgTools.ts # 消息/反馈类工具 │ └── auth_statsTools.ts # 统计分析类工具 ├── package.json # 项目依赖与配置清单 ├── tsconfig.json # TypeScript 编译配置 └── README.md # 项目说明文档

扩展新功能点 (新增 API 端点)

若需引入新的数据检索方法，请遵循以下流程：

1. 在 src/types/index.ts 中，根据需求定义或更新相应的数据结构类型。
2. 对于面向公众的接口，请在 src/tools/publicTools.ts 中注册新的工具调用函数。
3. 对于需要身份验证的接口，请定位至 src/tools/auth/ 目录下，并在功能相关的模块文件中添加相应的工具实现。

== WIKIPEDIA CONTEXT: XMLHttpRequest (XHR) ==

XMLHttpRequest (XHR) constitutes an Application Programming Interface realized as a JavaScript object. Its primary function involves facilitating the transmission of HTTP queries from a client-side web application running in a browser environment towards a designated web server. These methods grant browser-based scripts the capability to dispatch requests to the server subsequent to the initial page rendering, and subsequently receive data back.

XMLHttpRequest is fundamentally intertwined with the principles of Ajax (Asynchronous JavaScript and XML) programming methodology. Before the widespread adoption of Ajax, interactions with the server primarily relied on traditional mechanisms such as hyperlink activation or HTML form submissions, actions which typically resulted in a full page reload.

=== Genesis and Evolution ===

The underlying concept facilitating XMLHttpRequest was conceptualized around the year 2000 by engineers working on Microsoft Outlook. This concept was subsequently integrated into the Internet Explorer 5 browser release (1999). Crucially, the initial implementation did not utilize the standardized XMLHttpRequest string identifier. Instead, developers employed COM object instantiations: ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). As of the release of Internet Explorer 7 in 2006, comprehensive support for the unified XMLHttpRequest identifier became universal across all major browser platforms, including Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

==== Standardization Milestones ====

The World Wide Web Consortium (W3C) formally released a Working Draft specification for the XMLHttpRequest object on April 5, 2006. Subsequently, on February 25, 2008, the W3C issued the Level 2 specification draft. The Level 2 enhancements introduced functionality for monitoring the progress of ongoing events, enabling cross-site communication requests, and managing raw byte stream transfers. By the close of 2011, the specifications outlined in Level 2 were merged back into the foundational document. Development responsibility transitioned to the WHATWG toward the end of 2012, where it is now maintained as a living document utilizing Web IDL definitions.

== Operational Workflow ==

Executing a data request using XMLHttpRequest generally necessitates adherence to a sequence of distinct programming stages:

1. Instantiation: Formally create an XMLHttpRequest object instance by invoking its constructor.
2. Configuration: Invoke the open() method to define the HTTP method (e.g., GET, POST), specify the target resource URI, and determine the operational mode (synchronous or asynchronous).
3. Asynchronous Listener Setup: If operating asynchronously, establish an event handler (listener) configured to be triggered upon changes in the request's state.
4. Transmission: Initiate the data transfer process by executing the send() method.
5. Response Handling: Monitor state transitions within the registered event listener. Upon successful receipt of server-side data, it is typically aggregated within the responseText property. The object transitions to state 4 (the terminal "done" state) once processing concludes.

Beyond these fundamental steps, XHR offers substantial configuration options to govern request transmission and response processing. Custom HTTP headers can be injected to dictate server handling protocols. Data payload upload is managed by passing content directly into the send() invocation. Responses formatted in JSON can be automatically deserialized into navigable JavaScript objects, or alternatively, processed incrementally as segments arrive rather than waiting for full content assembly. Furthermore, requests can be deliberately terminated prematurely or subjected to timeouts.