文档集成服务器

概述MCP服务器

一个C#模型上下文协议（MCP）服务器，它与Outline API集成，以帮助Cursor使用Outline Wiki中的文档。此服务器是 只读的 专为文档消费而设计。

特性

• 大纲集成：通过REST API连接到大纲
• MCP协议支持：实现与Cursor无缝集成的模型上下文协议
• 只读操作：仅支持读取和搜索文档（无写入操作）
• 基于Web的服务器：在本地主机3001上作为HTTP服务器运行
• 文档访问：检索大纲文档并将其转换为markdown格式
• 搜索功能：使用大纲搜索API搜索大纲文档
• 文件重点：用于搜索和访问文档的专用工具

先决条件

• .NET 8.0 SDK或更高版本
• 具有API访问权限的大纲实例
• 用于身份验证的API令牌
• 游标IDE（用于MCP集成）

设置

1.克隆和构建

git clone <repository-url>
cd OutlineMCP
dotnet build

2.环境配置

设置以下环境变量：

# Windows
set OUTLINE_BASE_URL=https://your-outline-instance.com
set OUTLINE_API_TOKEN=your-api-token

# Linux/Mac
export OUTLINE_BASE_URL=https://your-outline-instance.com
export OUTLINE_API_TOKEN=your-api-token

备注：对于本地开发，您可以复制 appsettings.json.template 向 appsettings.json 并根据需要修改设置。这 appsettings.json 出于安全原因，git会忽略该文件。

3.获取大纲API令牌

1. 转到Outline实例
2. 使用您的帐户登录
3. 导航到“设置”→ API令牌
4. 点击“创建API令牌”
5. 为其命名（例如，“MCP服务器”）
6. 复制生成的令牌

运行MCP服务器

备注：此MCP服务器在localhost:3001上作为HTTP服务器运行。Cursor通过HTTP连接到它，而不是直接执行服务器。

选项1：开发模式

# Start the server in development mode
dotnet run

服务器将启动并监听MCP请求 http://localhost:3001/mcp.

选项2：生产模式

# Build for production
dotnet publish -c Release

# Run the published application
cd bin/Release/net8.0/publish
./OutlineMCP

选项3：作为Windows服务

# Install as a Windows service (requires admin privileges)
sc create "OutlineMCP" binPath="C:\path\to\OutlineMCP.exe"
sc start "OutlineMCP"

使用MCP服务器配置游标

1.安装Cursor IDE

从下载并安装Cursor https://cursor.sh

2.设置环境变量

在启动MCP服务器之前设置环境变量：

# Windows
set OUTLINE_BASE_URL=https://your-outline-instance.com
set OUTLINE_API_TOKEN=your-api-token

# Linux/Mac
export OUTLINE_BASE_URL=https://your-outline-instance.com
export OUTLINE_API_TOKEN=your-api-token

备注：这些环境变量必须在启动MCP服务器时设置，而不是在游标配置中设置。

3.在游标中配置MCP服务器

重要：此MCP服务器使用 HTTP传输 并在localhost:3001上作为web服务器运行。游标通过HTTP连接到它。

1. 创建MCP配置文件:

   • 项目特定：创建 .cursor/mcp.json 在您的项目目录中
   • 全球：创建 ~/.cursor/mcp.json 在您的主目录中

2. 添加MCP服务器配置:

{
 "mcpServers": {
    "OutlineWiki": {
      "url": "http://localhost:3001"
    }
  }
}

备注：在配置Cursor之前，请确保MCP服务器在localhost:3001上运行。

4.启动HTTP服务器

MCP服务器作为HTTP服务器运行。在配置Cursor之前，您需要启动它：

1. 启动HTTP服务器:
   复制

   dotnet run
   

服务器将启动并监听MCP请求 http://localhost:3001.

5.重新启动游标

配置MCP服务器后，重新启动Cursor以使更改生效。

6.验证连接

1. 确保MCP服务器在localhost:3001上运行
2. 打开Cursor，检查MCP服务器是否出现在可用工具中
3. 您可以通过询问有关文档的问题来测试连接

在游标中使用MCP服务器

1.验证连接

配置后，您应该在Cursor中看到可用的MCP服务器。您可以通过以下方式进行验证：

1. 打开命令面板(Ctrl+Shift+P)
2. 键入“MCP”查看可用的MCP命令
3. 服务器应显示为“大纲mcp”

2.查询示例

现在，您可以向Cursor询问有关文档的问题：

"Search for installation guides"
"Find configuration documentation"
"Look up troubleshooting steps"
"Search the wiki for best practices"

3.光标中的可用工具

MCP服务器提供以下工具：

MCP协议支持

此服务器实现以下MCP方法：

• initialize：处理服务器初始化
• tools/list：列出可用工具（只读操作）
• tools/call：执行只读工具
• resources/list：列出可用资源
• resources/read：读取资源内容

可用工具

可用资源

配置

服务器使用环境变量进行配置：

错误处理

服务器包括全面的错误处理：

• 身份验证错误：API令牌无效
• 网络错误：大纲API的连接问题
• 解析错误：JSON-RPC请求无效
• 资源错误：找不到文档或拒绝访问

发展

项目结构

OutlineMCP/
├── Services/
│   └── OutlineService.cs        # Outline API integration (read-only)
├── Models/
│   ├── McpRequest.cs            # MCP request model
│   ├── McpResponse.cs           # MCP response model
│   ├── McpError.cs              # MCP error model
│   ├── ToolCallParams.cs        # Tool call parameters model
│   └── ResourceReadParams.cs    # Resource read parameters model
├── Program.cs                   # Web application entry point
├── appsettings.json.template    # Configuration template
└── OutlineMCP.csproj           # Project file

添加新功能

1. 新工具：添加到switch语句中 HandleToolsCall
2. 新资源：添加到switch语句中 HandleResourcesRead
3. API终点：扩展 OutlineService 使用新的只读方法

安全

此服务器旨在 只读的 并且不支持对Outline实例的任何写入操作。这确保了：

• 无法创建、更新或删除任何文档
• 不能修改任何集合
• 服务器在生产环境中使用是安全的

故障排除

常见问题

1. 认证失败

   • 验证您的API令牌是否正确
   • 确保令牌具有必要的读取权限
   • 检查大纲URL是否正确

2. 服务器未启动

   • 检查端口3001是否可用
   • 验证环境变量是否设置正确
   • 确保。NET 8.0 SDK已安装

3. 网络错误

   • 检查您的互联网连接
   • 验证大纲URL是否正确
   • 确保您的防火墙允许HTTPS连接

4. 游标MCP集成问题

   MCP服务器未出现在光标中：

   • 验证MCP服务器是否在localhost:3001上运行
   • 检查HTTP服务器是否可在以下位置访问 http://localhost:3001/mcp
   • 验证游标配置使用了正确的HTTP端点
   • 配置更改后重新启动Cursor
   • 检查Cursor的开发人员控制台是否有错误

   游标中的身份验证错误：

   • 确保在MCP服务器环境变量中正确设置了API令牌
   • 验证令牌是否未过期
   • 请检查启动服务器时是否正确配置了环境变量

   服务器连接超时：

   • 验证服务器是否在localhost:3001上运行
   • 检查端口3001是否未被防火墙阻止
   • 确保HTTP端点 http://localhost:3001/mcp 可访问
   • 使用curl或浏览器手动测试端点

5. 工具执行错误

   • 检查服务器日志以获取详细的错误消息
   • 验证大纲API是否可访问
   • 确保搜索查询的格式正确

调试MCP服务器

1. 启用详细日志记录:

   复制

   {
     "Logging": {
       "LogLevel": {
         "Default": "Debug",
         "Microsoft": "Information"
       }
     }
   }
   

2. 手动测试服务器:

   复制

   curl -X POST http://localhost:3001/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
   

3. 检查游标日志:

   • 打开命令选项板(Ctrl+Shift+P)
   • 键入“开发人员：切换开发人员工具”
   • 检查Console选项卡是否存在与MCP相关的错误

日志记录

服务器使用结构化日志记录。在中设置日志级别 appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning"
    }
  }
}

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改（仅限只读操作）
4. 如果适用，添加测试
5. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

支持

对于问题和疑问：

1. 检查故障排除部分
2. 查看日志以了解错误详细信息
3. 在存储库上打开问题