Contexis MCP Server

Contexis MCP服务器

用于Contexis项目的模型上下文协议（MCP）服务器，允许大型语言模型（LLM）通过MCP标准与Contexis的项目进行交互。此服务器提供代码分析、探索和开发协助的功能。

什么是MCP？

这 模型上下文协议（MCP） 是一个开放标准，使人工智能助手和大型语言模型（LLM）能够以结构化和安全的方式与外部工具、数据源和系统进行交互。MCP提供了一个标准化的接口，用于：

• 工具集成：将AI助手连接到外部API、数据库和服务
• 数据访问：允许AI读取和分析文件、文档和结构化数据
• 动作执行：使人工智能能够执行文件操作、API调用和系统命令等操作
• 上下文管理：为人工智能提供相关背景和信息，以获得更好的响应

为什么选择MCP治疗挫伤？

Contexis项目包含有关AI代理、上下文、提示、工具和内存的丰富信息，这些信息对AI助手来说可能很有价值。MCP服务器通过以下方式弥合了这一差距：

• 暴露挫伤成分：使AI助手能够访问上下文、提示、工具和内存
• 标准化接口：使用MCP协议进行一致可靠的通信
• 安全：通过适当的验证提供对项目资源的受控访问
• 可扩展性：支持自定义功能和集成

特性

🔧 核心能力

• 上下文管理：列出并检索包含完整元数据的Contexis上下文
• 及时管理：使用变量替换访问、呈现和管理提示模板
• 工具集成：列出、检查和执行Contexis工具和集成
• 文件系统访问：使用安全验证搜索、读取和分析项目文件
• 内存访问：从Contexis知识库中搜索和检索记忆项

🚀 技术特性

• RESTful API：基于HTTP的MCP实现，易于集成
• 健康监测：内置健康检查和准备就绪端点
• 结构化日志记录：具有可配置级别的全面日志记录
• 配置管理：通过YAML文件和环境变量灵活配置
• 安全：路径验证、项目隔离和可选身份验证

🛠️ 发展特征

• 模块化架构：可扩展的自定义集成能力系统
• 综合测试：单元测试、集成测试和覆盖率报告
• Docker支持：使用安全最佳实践构建多阶段容器
• 开发工具：Makefile自动化、linting和开发脚本
• 文档：完整的API文档和使用示例

🔒 安全性和可靠性

• 路径验证：防止目录遍历攻击
• 项目隔离：限制对项目边界的文件访问
• 错误处理：全面的错误报告和优雅的降级
• 优雅地关闭：适当的清理和资源管理
• 非根执行：容器以非特权用户身份运行

安装

先决条件

• 转到1.21或更高版本
• Contexis项目目录

构建

# Clone the repository
git clone 
cd contexis-mcp-server

# Build the server
go build -o contexis-mcp-server main.go

# Or install dependencies and build
go mod tidy
go build -o contexis-mcp-server main.go

配置

服务器可以使用YAML配置文件或环境变量进行配置。

配置文件

创建一个 mcp-config.yaml 项目根目录中的文件：

# Server settings
host: "localhost"
port: 8080

# Logging
log_level: "info"

# Project directories (relative to project root)
contexts_dir: "contexts"
memory_dir: "memory"
prompts_dir: "prompts"
tools_dir: "tools"
tests_dir: "tests"

# Enabled capabilities
capabilities:
  - "contexts"
  - "prompts"
  - "tools"
  - "filesystem"
  - "memory"

环境变量

您还可以使用环境变量配置服务器：

export MCP_HOST=localhost
export MCP_PORT=8080
export MCP_LOG_LEVEL=info
export MCP_API_KEY=your-api-key

用法

启动服务器

# Start with default configuration
./contexis-mcp-server

# Start with custom project root
./contexis-mcp-server --project-root /path/to/contexis/project

# Start with custom config file
./contexis-mcp-server --config /path/to/config.yaml

# Enable verbose logging
./contexis-mcp-server --verbose

API终点

健康检查

curl http://localhost:8080/health

答复：

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "1.0.0"
}

列出功能

curl http://localhost:8080/capabilities

答复：

{
  "capabilities": [
    {
      "name": "contexts",
      "description": "Manage Contexis contexts",
      "methods": ["list", "get"]
    },
    {
      "name": "prompts",
      "description": "Manage Contexis prompts",
      "methods": ["list", "get", "render"]
    }
  ]
}

MCP请求

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "id": "req-123",
    "capability": "contexts",
    "method": "list",
    "params": {}
  }'

MCP能力

上下文

管理挫伤情况。

方法

• list：列出所有可用上下文
• get：按名称获取特定上下文

例子

# List all contexts
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "contexts",
    "method": "list"
  }'

# Get specific context
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "contexts",
    "method": "get",
    "params": {
      "name": "SupportBot"
    }
  }'

提示

管理Contexis提示模板。

方法

• list：列出组件的提示
• get：获取特定提示
• render：使用变量渲染提示（TODO）

例子

# List prompts for a component
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "prompts",
    "method": "list",
    "params": {
      "component": "SupportBot"
    }
  }'

# Get specific prompt
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "prompts",
    "method": "get",
    "params": {
      "component": "SupportBot",
      "name": "agent_response"
    }
  }'

工具

管理Contexis工具。

方法

• list：列出组件的工具
• get：获取特定工具
• execute：执行工具（TODO）

例子

# List tools for a component
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "tools",
    "method": "list",
    "params": {
      "component": "SupportBot"
    }
  }'

文件系统

访问项目文件。

方法

• search：按名称搜索文件
• read：读取文件内容
• list：列出目录内容（TODO）

例子

# Search for files
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "filesystem",
    "method": "search",
    "params": {
      "query": "main.go"
    }
  }'

# Read file content
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "filesystem",
    "method": "read",
    "params": {
      "path": "src/main.go"
    }
  }'

记忆

访问Contexis内存（TODO）。

方法

• search：搜索内存项
• get：获取特定的内存项
• list：列出内存项目

与LLM集成

Claude桌面集成

Claude Desktop是Claude AI的官方桌面应用程序，支持MCP服务器。这种集成允许Claude直接访问您的Contexis项目并与之交互，为开发和分析提供强大的人工智能帮助。

🚀 快速开始

1. 安装克劳德桌面 从 Anthropic网站

1. 构建MCP服务器:

   cd contexis-mcp-server
   make build

1. 配置Claude桌面:

- 打开克劳德桌面 - 转到“设置”→ 模型上下文协议 - 添加新的服务器配置

1. 添加服务器配置:

   {
     "mcpServers": {
       "contexis": {
         "command": "/path/to/contexis-mcp-server/contexis-mcp-server",
         "args": [
           "--project-root", "/path/to/your/contexis/project",
           "--verbose"
         ],
         "env": {
           "MCP_LOG_LEVEL": "info"
         }
       }
     }
   }

🎯 克劳德能做什么

借助Contexis MCP服务器，Claude可以：

• 分析上下文：查看并了解您的AI代理配置
• 检查提示：阅读提示模板并提出改进建议
• 检查工具：了解可用工具及其功能
• 搜索代码：查找并分析项目中的相关文件
• 提供指导：提供改进Contexis设置的建议
• 调试问题：帮助解决配置问题

💡 对话示例

分析上下文:

Claude, can you analyze the SupportBot context and suggest improvements?

复习提示:

Show me the prompt templates for the CustomerDocs component and suggest optimizations.

查找文件:

Search for all files related to memory configuration in the project.

代码审查:

Review the main.go file and suggest any improvements for error handling.

⚙️ 高级配置

自定义配置文件:

{
  "mcpServers": {
    "contexis": {
      "command": "/path/to/contexis-mcp-server/contexis-mcp-server",
      "args": [
        "--config", "/path/to/custom/mcp-config.yaml",
        "--project-root", "/path/to/your/contexis/project"
      ],
      "env": {
        "MCP_LOG_LEVEL": "debug",
        "MCP_API_KEY": "your-api-key"
      }
    }
  }
}

多项目支持:

{
  "mcpServers": {
    "contexis-main": {
      "command": "/path/to/contexis-mcp-server/contexis-mcp-server",
      "args": ["--project-root", "/path/to/main/project"]
    },
    "contexis-dev": {
      "command": "/path/to/contexis-mcp-server/contexis-mcp-server",
      "args": ["--project-root", "/path/to/dev/project"]
    }
  }
}

🔧 故障排除

服务器未启动:

• 检查二进制路径是否正确且可执行
• 验证项目根路径是否存在
• 启用详细日志记录： --verbose

克劳德无法连接:

• 确保服务器正在运行： curl http://localhost:8080/health
• 检查Claude Desktop日志中的连接错误
• 验证配置JSON语法

权限问题:

• 确保二进制文件具有执行权限： chmod +x contexis-mcp-server
• 检查项目目录中的文件权限

📊 最佳实践

1. 使用绝对路径：在配置中始终使用绝对路径
2. 启用日志记录：使用 --verbose 用于调试
3. 测试优先：在添加到Claude Desktop之前，请验证服务器是否正常工作
4. 保持更新：定期更新Claude Desktop和MCP服务器
5. 安全访问：将API密钥用于生产环境

其他MCP客户端

服务器实现了一个RESTful MCP接口，可以与任何支持HTTP传输的MCP客户端一起使用。

发展

项目结构

contexis-mcp-server/
├── main.go                 # Main entry point
├── go.mod                  # Go module file
├── go.sum                  # Go dependencies
├── mcp-config.yaml         # Sample configuration
├── README.md              # This file
└── internal/
    ├── config/            # Configuration management
    ├── server/            # HTTP server implementation
    ├── capabilities/      # MCP capabilities
    └── project/           # Contexis project operations

添加新功能

1. 在中创建新的处理程序 internal/capabilities/handlers.go
2. 在中注册处理程序 internal/capabilities/capabilities.go
3. 将该功能添加到功能列表中
4. 如果需要，更新配置架构

测试

# Run tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific test
go test ./internal/project -v

安全考虑

• 默认情况下，服务器在本地主机上运行
• 文件访问仅限于项目根目录
• 可以启用API密钥身份验证以提高安全性
• 所有文件操作都经过验证，以防止目录遍历

故障排除

常见问题

1. 端口已在使用中：更改配置中的端口
2. 未找到项目：确保项目根路径正确
3. 权限不足：检查项目目录中的文件权限

日志

启用详细日志记录以查看详细信息：

./contexis-mcp-server --verbose

健康检查

使用运行状况终结点验证服务器是否正在运行：

curl http://localhost:8080/health

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

许可证

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

支持

有关支持和问题：

• 在GitHub上创建问题
• 检查Contexis文档
• 加入Contexis社区