内容
"天机" — 思维模型MCP服务器
[
[](https://nodejs.org/)
[](https://github.com/modelcontextprotocol)
[](https://opensource.org/licenses/MIT)
[
[
>工具箱： 将系统化思维方法融入问题解决过程
## 目录
- [什么是"天机"?](#what-is-tianji)
- [核心功能](#core-features)
- [工具概览](#tools-overview)
- [探索工具](#exploration-tools)
- [问题解决工具](#problem-solving-tools)
- [创作工具](#creation-tools)
- [系统与学习工具](#system-and-learning-tools)
- [工具函数参数与返回值](#tool-function-parameters-and-return-values)
- [探索工具](#exploration-tools - [问题解决工具](#problem-solving1)
- [](#creation-tools- - [系统与学习工具](#system-and-learning-tools-1)
- [使用案例](#use-cases)
- [快速入门](#quick-start)
- [配置指南](#configuration-guide)
- [开发者文档](#developer-documentation)
- [开发环境设置](#development-environment-setup)
- [代码架构](#code-architecture)
- [API文档](#api-documentation)
- [扩展指南](#extension-guidelines)
- [测试](#testing)
- [构建与部署](#build-and-deployment)
- [编码规范](#coding-standards)
- [常见开发问题与排查](#common-development-issues-and-troubleshooting)
- [许可证](#license)
## 什么是"天机"?
"天机"是一个强大的思维模型MCP服务器，集成了数百种思维模型、框架和方法论，帮助用户更系统、全面地思考问题。通过MCP（模型上下文协议）接口，AI助手可以访问这些思维工具，并将结构化的思维方法无缝应用于对话中。"天机"的名字源自古代中国谚语"天之秘密不可泄露"，寓意帮助用户发现更深层次的思维模式和智慧。
## 核心功能
- **丰富的思维模型库**：包含决策理论、系统思维、概率思维等多个领域的经典思维模型
- **智能模型推荐**：根据问题推荐最合适的思维- **交互式推理：引导用户进行结构化的思考，逐步分析- **学习与适应系统**：通过用户反馈推荐算法
- **模型创建与组合**创建新模型或组合，生成创新的
## 工具概览
### 探索工具
-models**：列思维模型或筛选
- ****：按关键词搜索
- **get-categories**：获取所有类别
- **get-model-info**：获取思维
- **get**：获取与相关的其他模型
### 问题解决工具
- **-for-problem**：根据问题关键词推荐合适的思维模型
- **interactive-reasoning**：交互式推理过程指导
- **generate-validate-hypotheses**：多个假设并提供验证方法
- **explaining-process**：推理过程和应用模式
### 创作工具
- **create-th：创建新的思维模型
- **update-thinking-model**：更新现有思维模型的任意字段
- **emergent-model-design**：通过组合现有模型创建新的
- **delete-thinking-model**：删除不需要的思维模型
### 系统与学习工具
--started-guide**：新手指南
- **get-server：获取服务器版本信息
- **count-models统计当前思维模型总数
- **record-user-feedback**：记录用户对思维模型体验的反馈
- **detect-knowledge-gap**：检测用户查询中的知识空白
- **get-model-usage-stats**：获取思维模型的使用统计
- **analyze-learning-system**：分析思维模型学习系统的状态
## 工具与返回值
以下是对所有工具函数的详细参数和返回值的说明### 探索工具
#### `list-models`
列思维模型或按类别筛选。
**参数：**
- `lang`（必填，默认"zh"）：语言代码，选项：["zh", "en"]
- `category`（可选）：主类别名称
- `subcategory`（可选）：子类别名称（需提供主类别）
- `limit`（可选，默认100）：返回结果的限制数量
**返回值：**
```json
{
"models": [
{
"id": "模型ID",
"name": "模型名称",
"definition": "模型定义",
"category": "模型类别"
}
// ... 更多模型
],
"total": 查询的模型总数,
"filter": "应用的筛选条件"
}
```
#### `search-models`
按关键词搜索思维模型。
**参数：**
- `query`（必填）：搜索关键词
- `lang`（必填，默认"zh"）：语言代码，选项：["zh", "en"]
- `limit`（可选，默认10）：返回结果的限制数量
**返回值：**
```json
{
"results": [
{
"id": "模型ID",
"name": "模型名称",
"definition": "模型定义",
"purpose": "模型用途",
"match_score": 匹配分数,
"match_reasons": ["匹配原因1", "匹配原因2"]
}
// ... 更多匹配结果
],
"total": 匹配的模型总数,
"query": "搜索关键词"
}
```
#### `get-categories`
获取所有思维模型类别。
**参数：**
- `lang`（必填，默认"zh"）：语言代码，选项：["zh", "en"]
**返回值：**
```json
{
"categories": [
{
"name": "类别名称",
"count": 该类别下的模型数量,
"subcategories": [
{
"name":类别名称",
"count": 该子类别下的模型数量
}
// ... 更多子类别
]
}
// ... 更多类别
],
"total_categories": 类别总数,
"total_models": 所有模型总数
}
```
#### `get-model-info`
获取思维模型的详细信息。
**参数：**
- `model_id`（必填）：思维模型的唯一ID
- `fields`（可选，默认["basic"]）：返回的字段，选项all", "basic", "detail", "te "warnings", "visualizations"]
- `lang必填，默认"zh"）：语言代码，选项：["zh", "en"]
**返回值：**
{
"id": "模型ID",
"name": "模型名称",
"definition":定义",
"purpose": "模型用途",
// 根据fields参数返回不同详细程度的信息
": "模型类别",
"subcategories":1", "子类别2"],
"": ["应用步骤1", "应用步骤2popular_science_teaching": [
concept_name": "概念名称",
"ex "通俗解释"
}
],
ations": [
{
"limitation_name": "限制名称",
"description": "限制描述 }
],
"common_pitfalls {
"pitfall_name": "常见陷阱名称",
"description": "陷"
}
],
// 可视化相关字段（如需）
"visualizations": {
charts": [... "tables": [... "bar_charts": [...],
" [...]
}
}
```
#### `get-related-models与特定模型相关的其他模型。
**参数： `model_id`（必填）：思维模型的唯一- `lang`，默认"zh代码，选项：["zh", "en"]
- `limit`（可选，默认5）：返回限制数量
- `use_enhanced`（可选，默认true）：是否使用增强评估
**返回值：**
```json
{
"related_models": [
{
" "相关模型ID",
"name": "名称",
ity_score": 相似性得分,
"relationship_type": "关系类型",
"definition": "模型定义"
}
// ... 更多相关模型
],
"source_model": {
"id": "源模型ID",
name": "源模型名称"
}
}
```
### 问题解决工具
#### `recommend-models-for-problem`
根据问题关键词推荐模型。
**参数：**
- `problem_keywords`（必填）：问题关键词数组
- `problem_context`（可选）：问题的完整上下文描述
- `lang`（必填，默认"zh"）：语言代码，选项：["zhen"]
- `limit`（可选，默认返回结果的限制数量
- `use_learning_adjustment`（可选，默认true）：是否使用学习系统调整推荐
**返回值：**
```json
{
"models": [
{
"id": "模型ID",
"name": "模型名称",
"match_score": 匹配分数,
"match_reasons": ["匹配原因1", "匹配原因2"],
"definition": "模型定义",
"purpose": "模型用途",
"adjustment_reason": "调整原因（如使用学习调整）"
}
// ... 更多推荐模型
],
"learning_adjusted": 是否应用了学习调整,
"total_models_matched": 匹配的模型总数
}
```
#### `interactive-reasoning`
提供交互式推理过程指导。
**参数：**
- `initialContext`（必填）：初始问题或情况描述
- `reasoningStage`（必填）：当前推理选项：["information_gathering", "hyp "hypothesis_testing", "conclusioncurrentPathId`（可选）：当前推理在现有推理中）
- `required（可选）：需要额外信息的数组
- `lang必填，默认"zh"）：语言代码，选项：["zh", "en"]
**```json
"pathId":路径ID",
"currentStage": "",
"suggestedActions": [
"1",
"建议行动2"
"relevantModels": [
{
"id相关模型IDname": "相关模型名称",
"relevance_reason": "相关性原因"
}
// ... 更多相关模型
],
"nextStep": {
"action": "下一步行动",
"description": "下一步描述"
// 可能包含其他阶段特定数据
}
#### `generate-validate-hypotheses问题生成多个假设并提供验证方法。
**参数：**
- `problem`（必填）：要
- `context`（必填）：与背景信息
- `lang`（必填"zh"）：语言代码，选项：["zh", "en"]
**返回值：**
```json
{
"problem_statement": "问题陈述 "hypotheses": [
{
": "假设内容",
"rationale": "形成理由",
"validation_methods": [
"method": "验证方法",
_outcome": "",
"resources "所需资源"
// ...方法
"potential_biases潜在偏见1", "潜在偏见2"]
}
//假设
],
applicable_thinking_models": [
{
": "",
"name": "适用模型名称",
"relevance": "相关性描述"
}
// ...模型
]
}
```
#### `explain-reasoning-process`
解释模型的推理过程和应用的思维模式。
**参数：**
- `problemDescription`（必填）：问题或情况描述
- `reasoningSteps`（必填）：推理步骤数组，每个步骤包括：
- `description`（必填）：推理步骤描述
- `modelIds`（可选）：使用的思维模型ID数组
- `evidence`（可选）：支持证据数组
- `confidence`（可选，默认0.8）：置（0-1）
- `conclusion`（必填）：推理结论
- `lang`，默认"zh"）：语言代码，选项：["zh", "en"]
**返回值：**
```json
{
"reasoning_path": {
"problem": "问题描述",
"steps": [
{
"description": "步骤描述",
"models_applied": [
{
"id": "应用模型ID",
"name": "应用模型名称",
"explanation": "模型应用解释"
}
],
"cognitive_biases_avoided": ["避免的认知偏见1", "避免的认知偏见2"],
"confidence": 置信度值
}
// ... 更多推理步骤
],
"con结论",
meta_cognition_ins ["元认知洞察1", "元2"]
"visualization推理路径可视化（如流程图）"
}
```
### 创作工具
#### `create-thinking-model`
创建新的思维模型。
**参数：**
- `id`（必填）：模型的唯一标识符
- `name`（必填）：模型名称
- `definition`（必填）：模型的简洁定义
- `purpose`（必填）：模型的主要用途和使用场景
- `category`（模型的主类别
- `lang`，默认"zh"）：模型的语言，选项：["zh", "en"]
- `subcategories`（可选）：模型的子类别列表
-（可选）：模型的关联标签
- `author`（可选）：模型作者
- `source`（可选）：模型来源
- `prompt`（可选）：详细的提示/角色扮演指南
- `example`（可选）：模型使用示例
- `use_cases`（可选）：模型的用例
- `interaction`（可选）：与用户交互的指南
- `constraints`（可选）：模型使用的约束
- `popular_science_teaching`（可选）：模型的科普教学
- `limitations`（可选）：模型的局限性
- `common_pitfalls`（可选）：使用模型时的常见陷阱
- `common_problems_solved`（可选）：模型解决的常见问题
- 各种可视化数据（可选）：流程图、表格、条形图、列表等
**返回值：**
```json
{
"status": "操作状态",
"message": "操作消息",
"model_id": "创建的模型ID"
}
```
#### `update-thinking-model`
更新现有思维模型的任意字段。
**参数：**
- `model_id`（必填）：要更新的模型ID
- 其他要更新的字段（可选）：与`create-thinking-model`参数相同
**返回值：**
```json
{
"status": "操作状态",
"message": "操作消息",
"updated_fields": ["更新字段1", "更新字段2"]
}
```
#### `emergent-model-design`
通过组合现有思维模型创建新的思维模型。
**参数：**
- `source_model_ids`（必填）：组合的源模型ID列表，至少2个，最多10个
- `target_model_id`（必填）：新模型的唯一标识符
- `target_model_name`（必填）：新模型名称
- `design_goal`（必填）：设计目标和用途描述
- `connection_description`（可选）：源模型如何描述
- `category`（可选）：新模型的主类别
- `lang`（必填，默认"zh"）：模型的语言，选项：["zh", "en"]
**返回值：**
```json
{
"status": "操作状态",
"message": "操作消息",
"model_id": "创建的模型ID",
"emergent_properties": ["涌现属性1涌现属性2"],
"source_models_used": [
{
"id": "ID",
"name": "源模型名称",
"contribution": "对新模型的 }
// ... 更多源模型 ]
}
```
#### `delete-thinking-model不需要的思维模型。
**参数：**
- `model_id`）：要删除的
- `lang`（必填，默认"zh"）：语言代码，选项：["zh", "en"]
- `confirm`（必填）：确认删除，必须为true
**返回值：**
```json
{
"status": "操作状态",
"message": "操作消息",
"deleted_model_id": "删除的模型ID"
}
```
### 系统与学习工具
#### `get-started-guide`
获取新手指南。
**参数：**
- `user_objective`（可选，默认"explore"）：用户目标，选项：["explore", "solve_problem", "create_model", "learn_tools"]
- `expertise_level`（可选，默认"beginner"）：用户经验水平，选项：["beginner", "intermediate", "advanced"]
-`（必填，默认"zh语言代码，选项：["zh", "en"]
**返回值：**
```{
"welcome_message": "欢迎消息",
"system_overview":概述",
"suggested_first_steps": [
{
"step":描述",
"tool": "推荐工具",
"example": ""
// ... 更多 ],
"recommended_models": "id": "推荐模型ID",
"name": "推荐",
"purpose": "模型用途"
}
// ... 更多推荐 ],
"learning_path":路径建议",
"additional额外资源1", "额外"]
}
```
#### `获取服务器版本`
获取服务器版本和状态信息。
**参数：**
- 无
**返回值：**
```json
{
"version": "版本号",
"build_date": "编译日期",
"api_version": "API 版本",
"status": "服务器状态",
"uptime": 以秒为单位的运行时间,
"models_loaded": 已加载的模型总数
}
```
#### `统计模型数量`
统计当前可用的思维模型总数。
**参数：**
- `lang` （必填，默认 "zh"）：语言代码，选项：["zh", "en"]
**返回值：**
```json
{
"total_count": 模型总数,
"language": "语言代码",
"category_counts": {
"类别1": 该类别下的模型数量,
"类别2": 该类别下的模型数量
// ... 更多类别统计
}
}
```
#### `记录用户反馈`
记录用户对思维模型体验的反馈。
**参数：**
- `modelIds` （必填）：相关思维模型的 ID 数组
- `context` （必填）：应用模型的上下文或问题描述
- `feedbackType` （必填）：反馈类型，选项：["helpful", "not_helpful", "incorrect", "insightful", "confusing"]
- `comment` （可选）：详细的反馈说明或评论
- `applicationResult` （可选）：模型应用结果描述
- `suggestedImprovements` （可选）：建议的改进措施数组
- `lang` （必填，默认 "zh"）：语言代码，选项：["zh", "en"]
**返回值：**
```json
{
"status": "操作状态",
"message": "操作消息",
"insights": "从反馈中获得的洞察"
}
```
#### `检测知识空白`
检测用户查询中的知识空白。
**参数：**
- `query` （必填）：用户查询或问题
- `matchThreshold` （可选，默认 0.5）：匹配阈值，低于此值的认为是知识空白
- `lang` （必填，默认 "zh"）：语言代码，选项：["zh", "en"]
**返回值：**
```json
{
"knowledge_gaps": [
{
"concept": "缺失的概念",
"match_score": 匹配分数,
"suggested_models": [
{
"id": "建议的模型 ID",
"name": "建议的模型名称",
"relevance": "相关性描述"
}
// ... 更多建议的模型
],
"learning_resources": ["学习资源 1", "学习资源 2"]
}
// ... 更多知识空白
],
"query_coverage": 查询覆盖率,
"recommendations": ["建议 1", "建议 2"]
}
```
#### `获取模型使用统计`
获取思维模型的使用统计数据。
**参数：**
- `modelId` （必填）：思维模型的唯一 ID
- `lang` （必填，默认 "zh"）：语言代码，选项：["zh", "en"]
**返回值：**
```json
{
"model_id": "模型 ID",
"model_name": "模型名称",
"usage_count": 使用次数,
"average_rating": 平均评分,
"feedback_distribution": {
"helpful": 有帮助的反馈次数,
"not_helpful": 无帮助的反馈次数,
"incorrect": 错误的反馈次数,
"insightful": 有见地的反馈次数,
"confusing": 令人困惑的反馈次数
},
"common_usage_contexts": ["常见使用场景 1", "常见使用场景 2"],
"trend": "使用趋势描述",
"related_models_also_used": [
{
"id": "相关模型 ID",
"name": "相关模型名称",
"co_occurrence_count": 共同出现次数
}
// ... 更多相关模型
]
}
```
#### `分析学习系统`
分析思维模型学习系统的状态。
**参数：**
- `lang` （必填，默认 "zh"）：语言代码，选项：["zh", "en"]
**返回值：**
```json
{
"system_health": {
"total_feedback_count": 总反馈次数,
"knowledge_coverage": 知识覆盖率,
"adaptation_score": 适应性评分
},
"top_performing_models": [
{
"id": "模型 ID",
"name": "模型名称",
"effectiveness_score": 有效性评分
}
// ... 更多表现良好的模型
],
"identified_gaps": ["已识别的空白 1", "已识别的空白 2"],
"learning_trends": ["学习趋势 1", "学习趋势 2"],
"improvement_suggestions": ["改进建议 1", "改进建议 2"]
}
```
## 使用案例
### 解决复杂问题
面对复杂问题时，系统可以推荐多个思维模型，帮助用户从不同角度分析问题，避免思维盲点。
### 提升思维质量
通过结构化的思维过程，避免常见的认知偏差，做出更理性的决策。
### 学习思维模型
系统不仅提供思维模型的定义，还包括详细的教学内容、应用示例和笔记，帮助用户掌握各种思维工具。
### 创建自定义模型
当现有模型无法满足需求时，用户可以创建新的思维模型或组合现有的模型，创造创新的思维框架。
## 快速入门
### 安装（本地开发）
如果要在本地运行和开发该项目：
```bash
git clone https://github.com/yourusername/thinking-models-mcp.git # 替换为你的仓库地址
cd thinking_models_mcp
npm install
npm run build
```
### 启动服务器（本地开发）
1. **正常启动（stdio 模式）**
在项目根目录下运行：
```bash
node build/thinking_models_server.js
```
或使用 npm 脚本（如果在 package.json 中配置了）：
```bash
npm run start
```
## 配置指南
您可以将思维模型 MCP 服务器集成到任何支持 MCP 协议的客户端中。以下是两种不同的实现方法：
### 方法 1：使用本地 Node.js 运行“Tianji”服务器
此方法需要您在本地安装和配置“Tianji”服务器代码，适用于需要自定义开发或修改服务器代码的场景。
```json
{
"mcpServers": {
"tianji": { // "Tianji" 服务器名称
"command": "node",
"args": [
"e:\\thinking_models_mcp\\build\\thinking_models_server.js" // 替换为你的实际路径
]
}
}
// ... 其他配置 ...
}
```
### 方法 2：使用 NPX 从远程 npm 包启动服务器
此方法更简单，不需要本地安装完整的代码，直接从 npm 仓库拉取并运行包。
```json
{
"mcpServers": {
"thinking-models": {
"command": "npx",
"args": [
"--no-cache", // 避免使用缓存版本，确保每次都使用最新版本
"@thinking-models/mcp-server" // npm 包名称
// 如果需要指定版本： "@thinking-models/mcp-server@latest"
]
}
}
// ... 其他配置 ...
}
```
**命令行参数说明：**
- **`node`**：直接使用本地 Node.js 运行 JavaScript 文件
- **`npx`**：npm 包运行器，允许在不全局或本地安装的情况下执行 npm 包中的命令
- **`--no-cache`**：禁用缓存，确保每次都获取最新版本的包，避免因缓存问题而使用过时的功能
> **重要注意事项**：服务器数据将自动保存在安装目录的 `data` 文件夹中。即使服务重启，之前的数据也将保留，无需额外配置。建议使用 `--no-cache` 参数，确保每次都获取最新版本，避免因缓存问题而使用过时的功能。
### 基本用法
“Tianji” 服务器启动后，您可以通过 MCP 客户端发送请求，访问思维模型工具。例如：
```json
1. “Tianji” 的当前版本号是多少？
2. “Tianji” 目前有多少个思维模型可供我使用？
3. 我想检查“Tianji” 中有哪些类型的思维模型，告诉我总共有多少个类别？
4. 我遇到了 XXXX 事件，但不知道该怎么办，请“Tianji” 推荐一些可以帮助我解决问题的思维模型。
```
如果配置正确，客户端应该能够调用服务器并返回结果。
## 开发者文档
本部分适用于想要了解、自定义或扩展思维模型 MCP 服务器的开发者。
### 开发环境设置
#### 环境要求
- Node.js >= 18.0.0
- npm >= 8.0.0 （或兼容的包管理器，如 yarn, pnpm）
- TypeScript 5.x
#### 安装依赖（本地开发）
```bash
# 假设你已经克隆了仓库并进入了项目目录
npm install
```
#### 开发模式（本地开发）
```bash
# 监视模式，当更改时自动重新编译 TypeScript 文件
npm run watch
# 在另一个终端中，启动开发服务器（通常运行 build 目录中的编译文件）
# 您可能需要像 nodemon 这样的工具来自动重启服务器
npm run start:dev # （假设您已在 package.json 中配置了此脚本）
```
### 代码架构
#### 文件结构（示例）
```
thinking_models_mcp/
├── build/ # 编译后的 JavaScript 文件
├── src/ # TypeScript 源代码
│ ├── thinking_models_server.ts # 主要服务器逻辑和工具注册
│ ├── types.ts # TypeScript 类型定义
│ ├── utils.ts # 公共实用函数
│ ├── similarity_engine.ts # 相似度计算逻辑
│ ├── reasoning_process.ts # 推理过程管理
│ ├── learning_capability.ts # 学习系统功能
│ ├── recommendations.ts # 模型推荐逻辑
│ └── response_types.ts # API 响应类型定义
├── thinking_models_db/ # 思维模型数据库
│ ├── zh/ # 中文模型（JSON 文件）
│ └── en/ # 英文模型（JSON 文件）
├── package.json # 项目依赖和脚本
├── tsconfig.json # TypeScript 编译器配置
└── README.md # 本文档
```
#### 核心模块
1. **服务器核心（thinking_models_server.ts）**
* 初始化 MCP 服务器实例（`McpServer` from `@modelcontextprotocol/sdk`）
* 注册所有可用的工具，定义其参数模式（使用 `zod`）和处理函数
* 加载和管理思维模型数据
* 处理客户端请求并路由到适当的工具
2. **思维模型类型（types.ts）**
* 定义核心 `ThinkingModel` 接口，描述模型的数据结构
* 其他与模型相关的 TypeScript 类型和接口
3. **相似度计算引擎（similarity_engine.ts）**
* `calculateQueryMatch`：计算用户查询与思维模型之间的匹配度
* `calculateKeywordRelevance`：计算关键词列表与思维模型的相关性
4. **推理过程管理（reasoning_process.ts）**
* 用于构建、管理和可视化结构化的推理路径
5. **学习系统（learning_capability.ts）**
* `recordUserFeedback`：记录用户对模型使用的反馈
* `detectKnowledgeGap`：根据用户查询和反馈检测知识空白
* `adjustModelRecommendations`：根据学习数据调整模型推荐
### API 文档
#### 服务器 API
服务器通信模式：
1. **stdio API**
* 通过标准输入/输出与客户端通信。
* 遵循 MCP 协议规范。
* 通常由客户端（如 Cursor、Claude Desktop）自动管理。
#### 工具 API
每个工具都使用 `server.tool()` 方法注册，包含：
1. **工具名称**（字符串）：客户端调用时使用的名称。
2. **工具描述**（字符串）：工具功能简述。
3. **参数模式**（Zod 对象）：使用 `zod` 库定义工具接受的参数及其类型、描述和约束。
4. **处理函数**（异步函数）：接收验证的参数对象，执行工具逻辑，返回符合 MCP 协议的响应。
##### 工具注册示例
```typescript
// 文件路径：src/thinking_models_server.ts
// ... 导入 ...
server.tool(
"get-model-count-by-category", // 工具名称
"获取指定类别下思维模型的数量", // 工具描述
{ // 参数模式（Zod 模式）
category: z.string().describe("要查询的思维模型的主要类别"),
lang: z.enum(["zh", "en"] as const).default("zh").describe("语言代码（'zh' 或 'en'）")
},
async ({ category, lang }) => { // 处理函数
try {
const modelsInBuffer = MODELS[lang] || []; // MODELS 是已加载的模型缓存
const count = modelsInBuffer.filter(m => m.category === category).length;
log(`工具 'get-model-count-by-category' 调用：category=${category}, lang=${lang}, count=${count}`);
return {
content: [{
type: "text",
text: JSON.stringify({ category, lang, count }, null, 2)
}]
};
} catch (error: any) {
log(`工具 'get-model-count-by-category' 执行错误：${error.message}`);
return {
content: [{
type: "text",
text: JSON.stringify({ error: "获取模型数量失败", message: error.message }, null, 2)
}]
};
}
}
);
```
### 扩展指南
#### 添加新工具
1. 在 thinking_models_server.ts（或相关模块文件）中，使用 `server.tool()` 方法注册你的新工具，如上例所示。
2. 定义清晰的参数模式和描述。
3. 实现工具的处理函数，确保包含错误处理和日志记录。
4. 重新编译项目（`npm run build`）。
#### 创建新思维模型
1. 在 zh（中文）或 en（英文）目录中创建新的 `.json` 文件。
2. 文件名通常为模型的 ID（例如 `new_decision_matrix.json`）。
3. 文件内容应符合 `ThinkingModel` 接口（定义在 types.ts）结构。示例：
```json
{
"id": "new_decision_matrix",
"name": "新决策矩阵模型",
"definition": "一种用于评估选项的多准则结构化方法。",
"purpose": "帮助做出复杂的理性选择。",
"category": "决策",
"subcategories": ["多准则决策"],
"tags": ["决策", "矩阵", "评估", "选择"],
"use_cases": ["产品功能优先级", "供应商选择"],
// ... 其他字段，如 popular_science_teaching, limitations, common_pitfalls, visualizations, etc.
}
```
4. 服务器将自动加载新模型，或者如果启用了文件监视，它也会在保存时重新加载。
#### 修改推荐算法
推荐逻辑主要位于 similarity_engine.ts 和 recommendations.ts 中。
- **similarity_engine.ts**：包含用于计算文本相似度和关键词相关性的核心算法。你可以调整这些算法的权重、使用的方法（如 TF-IDF、嵌入向量等）以提高匹配精度。
- **recommendations.ts**：包含 `getModelRecommendations` 等函数，它们使用相似度引擎的结果生成最终的模型推荐列表。你可以修改这里的逻辑，例如如何组合不同来源的分数或如何根据上下文调整推荐。
### 测试
项目通常使用 Jest 等测试框架。
#### 编写测试
在 `tests` 目录中为你的模块或函数创建测试文件（例如 `tests/my_tool.test.ts`）。
```typescript
// tests/example_tool.test.ts
import { server, loadModels } from '../src/thinking_models_server'; // 假设服务器实例被导出
import { ThinkingModel } from '../src/types';
// 模拟 MCP 客户端请求
async function callTool(toolName: string, params: any) {
const toolDefinition = server.capabilities.tools[toolName];
if (!toolDefinition || !toolDefinition.execute) {
throw new Error(`工具 ${toolName} 未找到或不可执行`);
}
// 实际测试可能需要更复杂的模拟以匹配 MCP SDK 上下文）
return toolDefinition.execute(params, {} as any);
}
describe('我的自定义工具测试', () => {
beforeAll(async () => {
// 加载测试模型数据（如果需要）
await loadModels('zh'); // 加载中文模型
});
test('get-model-count-by-category 应返回正确的数量', async () => {
const response = await callTool('get-model-count-by-category', { category: '决策', lang: 'zh' });
const result = JSON.parse(response.content[0].text);
expect(result.category).toBe('决策');
expect(result.count).toBeGreaterThanOrEqual(0); // 特定数量取决于你的测试数据
});
});
```
#### 运行测试
在 package.json 中配置测试脚本：
```json
{
"scripts": {
"test": "jest"
}
```
然后运行：
```bash
npm test
```
### 构建和部署
#### 构建项目
```bash
npm run build
```
#### 部署选项
**部署为独立的 Node.js 服务器**
* 将整个项目（或至少 build 目录、node_modules、package.json、thinking_models_db）复制到服务器
* 运行服务器：
```bash
node build/thinking_models_server.js
```
* 或使用进程管理器（如 `pm2`）保持服务器运行：
```bash
npm install -g pm2
pm2 start build/thinking_models_server.js --name "thinking-models-mcp"
pm2 save
```
#### 编码风格
- 遵循一致的编码风格（例如，使用 Prettier 和 ESLint）。
- 使用 TypeScript 的强类型特性，避免在非必要情况下使用 `any` 类型。
- 编写清晰、自我解释的代码，并为复杂的逻辑添加注释。
#### 命名约定
- **函数和变量**：`camelCase`（例如，`calculateSimilarity`）
- **类和接口**：`PascalCase`（例如，`ThinkingModel`，`McpServer`）
- **常量**：`UPPER_SNAKE_CASE`（例如，`DEFAULT_PORT`）
- **文件名**：`snake_case.ts` 或 `kebab-case.ts`（在项目内保持一致性）
#### 文档标准
- 为所有公共 API（函数、类、接口）编写 JSDoc/TSDoc 注释。
- 在 README 和其他文档中清晰地解释项目的功能和用法。
- 保持文档与代码同步。
### 常见开发问题与故障排除
#### 1. 模型文件未加载或加载错误
- **检查路径**：确保在 `SUPPORTED_LANGUAGES` 中定义的路径相对于编译后的 `thinking_models_server.js` 文件是正确的。
- **JSON 格式**：确保所有模型 `.json` 文件都是有效的 JSON，并且符合 `ThinkingModel` 接口的结构。
- **文件权限**：确保服务器进程具有读取模型目录和文件的权限。
- **日志**：查看服务器启动日志，通常在加载模型时包含错误信息。
#### 2. API 请求失败或工具未找到
- **服务器运行状态**：确认服务器已成功启动且无错误。
- **工具名称**：确认客户端调用的工具名称与服务器中注册的名称（区分大小写）完全匹配。
- **参数格式**：确保发送到工具的参数符合其 Zod 模式定义。
#### 3. 相似度计算或推荐不准确
- **模型数据质量**：`definition`、`purpose`、`tags`、`keywords` 等字段对于相似度计算至关重要。确保这些字段内容丰富且准确。
- **算法调整**：您可能需要在 `similarity_engine.ts` 中调整算法参数或权重。
- **学习系统**：如果启用了学习系统，请检查反馈数据是否正确记录和应用。
#### 最佳实践
- **日志记录**：使用 `log()` 函数（或更复杂的日志记录库）记录关键操作、错误和调试信息。
- **错误处理**：在所有工具函数和异步操作中实施强大的错误处理，并向客户端返回有意义的错误消息。
- **模块化**：将不同的功能（例如相似度计算、学习系统、工具实现）组织成独立的模块。
- **配置管理**：使用环境变量或配置文件进行可配置项的管理，例如端口和路径。
## 许可证
本项目在 MIT License 下开源。
连接信息
猜你喜欢
暂无推荐服务器