OSF API MCP服务器
一种模型上下文协议（MCP）服务器，为OSF（开放科学框架）API v2 Swagger规范提供高效的搜索功能。该服务器使LLM能够快速查找相关的API端点、模式和文档，而无需消耗过多的令牌。
特性
- 端点搜索：按路径、HTTP方法、operationId或标记查找API终结点
- 基于标签的搜索：浏览按类别/标签分组的端点
- 架构搜索：发现数据模型和响应模式
- 全文搜索：在摘要、描述和参数文档中搜索
- 详细端点信息：获取特定端点的完整规范
- 标签列表：查看所有可用的API类别及其说明
安装
npm install
npm run build用法
作为MCP服务器
添加到您的Claude Desktop配置(claude_desktop_config.json):
{
"mcpServers": {
"osf-api": {
"command": "node",
"args": ["/path/to/osf-api-mcp/dist/index.js"]
}
}
}您还可以将此服务器添加到 /.mcp.json 要使用项目范围配置它，请执行以下操作：
{
"mcpServers": {
"osf-api-docs": {
"command": "node",
"args": ["/path/to/osf-api-mcp/dist/index.js"]
}
}
}MCP检验员测试
npm run build
npx @modelcontextprotocol/inspector node dist/index.js可用工具
1.搜索_积分
按各种条件搜索API端点。
参数：
path（可选）：搜索包含此路径字符串的端点method（可选）：按HTTP方法过滤（GET、POST、PATCH、DELETE等）operationId（可选）：按操作ID搜索（部分匹配）tag（可选）：按标签名称筛选（部分匹配）limit（可选）：最大结果数（默认值：10）
例子：
{
"path": "/files",
"method": "GET",
"limit": 5
}2.搜索_by_tag
查找按特定标签/类别分组的所有端点。
参数：
tag（必填）：要搜索的标签名称（部分匹配）includeDescription（可选）：包括标记描述（默认值：false）
例子：
{
"tag": "Files",
"includeDescription": true
}3.搜索模式
搜索响应模式和数据模型。
参数：
schemaName（可选）：模式/模型名称（例如，“文件”、“节点”）property（可选）：搜索包含此属性的架构path（可选）：获取特定端点的架构method（可选）：HTTP方法（如果指定了路径，则需要）
例子：
{
"schemaName": "File"
}4.全文搜索
使用相关性排名执行全文搜索。
参数：
query（必填）：搜索查询字符串limit（可选）：最大结果数（默认值：10）
例子：
{
"query": "upload file storage",
"limit": 5
}5.get_endpoint_details
获取特定端点的完整详细信息。
参数：
path（必填）：精确的端点路径（例如，“/files/{file_id}/”）method（必填）：HTTP方法（GET、POST等）
例子：
{
"path": "/files/{file_id}/",
"method": "GET"
}6.列表标签
获取所有可用的标签/类别及其描述。
参数： 无
7.list_endpoints
列出所有可用的带有分页的OSF API v2终结点。
参数：
limit（可选）：要返回的最大端点数（默认值：50）offset（可选）：要跳过的终结点数（默认值：0）
例子：
{
"limit": 20,
"offset": 0
}API 规范
此服务器对完整的OSF API v2规范进行索引：
- 250个API终点
- 40个标签/类别
- 全面的模式定义
- 完整的参数和响应文档
规范文件位于 模式/osf-api/swagger.json.
建筑
项目结构
osf-api-mcp/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # MCP server implementation
│ ├── server.test.ts # Server tests
│ ├── types.ts # TypeScript type definitions
│ ├── __mocks__/ # Test mocks
│ │ └── swagger-loader.mock.ts
│ ├── __fixtures__/ # Test fixtures
│ │ ├── swagger-minimal.json
│ │ └── swagger-edge-cases.json
│ ├── search/ # Search implementations
│ │ ├── endpoint-search.ts
│ │ ├── endpoint-search.test.ts
│ │ ├── tag-search.ts
│ │ ├── tag-search.test.ts
│ │ ├── schema-search.ts
│ │ ├── schema-search.test.ts
│ │ ├── fulltext-search.ts
│ │ ├── fulltext-search.test.ts
│ │ └── list-endpoints.ts # Endpoint listing with pagination
│ └── utils/
│ ├── swagger-loader.ts # Swagger spec loader & indexer
│ └── swagger-loader.test.ts
├── schema/
│ └── osf_api/
│ ├── swagger.json # OSF API specification (full)
│ └── swagger_short.json # OSF API specification (abbreviated)
├── vitest.config.ts # Vitest configuration
└── eslint.config.js # ESLint configuration演出
- 启动时间：\<1秒（加载和索引3.1MB规格）
- 内存使用：\<50MB（包括所有索引）
- 搜索响应：对于大多数查询，\<100ms
服务器在启动时构建内存索引：
- 基于路径的端点索引
- 标签到端点映射
- 按名称和属性定义架构
- 用于快速文本搜索的全文倒排索引
发展
构建
npm run build观看模式
npm run watch直接运行
npm run dev测试
使用Vitest运行测试：
npm test # Run tests in watch mode
npm run test:run # Run tests once
npm run test:coverage # Run tests with coverage report语句、函数和行的覆盖率阈值配置为80%，分支为75%。
代码检查
运行ESLint：
npm run lint # Check for linting issues
npm run lint:fix # Fix linting issues automatically许可证
阿帕奇-2.0
关于OSF
开放科学框架（OSF）是由开放科学中心维护的免费开源服务。它为研究项目管理、文件存储和学术出版提供了一个协作平台。
有关OSF API的更多信息，请访问：
- API文件：https://developer.osf.io/
- OSF网站：https://osf.io/
- 技术支持：https://help.osf.io/