Log4 MCP

Log4MCP-Swift模型上下文协议记录器

一个用Swift实现的高性能、线程安全的日志服务器，通过JSON-RPC 2.0上的模型上下文协议（MCP）进行通信。非常适合分布式日志记录、多租户应用程序，以及将日志记录功能集成到Claude AI上下文中。

特性

• 符合MCP标准：实现模型上下文协议以实现无缝集成
• 异步/等待：基于Swift的现代并发模型与参与者
• 多个日志级别：跟踪、调试、信息、警告、错误、致命
• 线程安全：使用基于参与者的并发性进行线程安全日志记录
• 灵活的存储：可配置的最大日志条目的自动轮换
• TCP服务器：基于TCP的JSON-RPC 2.0（主要访问方法）
• 标准支持：可选JSON-RPC 2.0，通过stdin/stdout进行MCP集成
• 命令行配置：通过CLI参数轻松设置

建筑

# Build the project
swift build

# Run with default settings
swift run Log4MCP

# Run with custom configuration
swift run Log4MCP --port 3000 --log-level DEBUG --verbose

# Run in stdio mode (for MCP integration)
swift run Log4MCP --stdio --log-level DEBUG --verbose

命令行选项

Log4MCP [OPTIONS]

Options:
  -p, --port PORT              Port to listen on (default: 3000) [TCP mode]
  -h, --host HOST              Host to bind to (default: 0.0.0.0) [TCP mode]
  -m, --max-entries NUM        Maximum log entries per logger (default: 1000)
  -l, --log-level LEVEL        Default log level (default: INFO)
                               Valid levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
  -v, --verbose                Enable verbose output to stderr
  --stdio                      Use stdio mode instead of TCP (default: TCP server)
  --help                       Show this help message

Server Modes:
  TCP (default)  - Listens on specified host:port for client connections
  Stdio          - Reads JSON-RPC requests from stdin, writes responses to stdout

Examples:
  swift run Log4MCP --log-level DEBUG --max-entries 5000 --verbose
  swift run Log4MCP --port 8080 --host 127.0.0.1 --log-level DEBUG
  swift run Log4MCP --stdio --log-level DEBUG --verbose

MCP方法

log.message

将消息记录到特定的记录器。

请求：

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "log.message",
  "params": {
    "loggerId": "myapp",
    "level": "INFO",
    "message": "Application started successfully"
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": { "success": true }
}

log.get条目

检索已记录的条目，可选择按日志级别进行筛选。

请求：

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "log.getEntries",
  "params": {
    "loggerId": "myapp",
    "level": null
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "entries": [
      {
        "timestamp": "2024-11-25T21:15:00Z",
        "level": "INFO",
        "message": "Application started",
        "logger": "myapp",
        "thread": "main",
        "file": "main.swift",
        "line": 42,
        "method": "main()"
      }
    ]
  }
}

log.clear

清除特定记录器的所有日志条目。

请求：

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "log.clear",
  "params": {
    "loggerId": "myapp"
  }
}

log.setLevel

更改特定记录器的日志级别。

请求：

{
  "jsonrpc": "2.0",
  "id": "4",
  "method": "log.setLevel",
  "params": {
    "loggerId": "myapp",
    "level": "DEBUG"
  }
}

系统能力

报表服务器功能。

请求：

{
  "jsonrpc": "2.0",
  "id": "5",
  "method": "system.capabilities"
}

项目结构

Log4MCP/
├── Sources/Log4MCP/
│   ├── Log4MCP.swift          - Main entry point
│   ├── Config.swift           - Command-line configuration
│   ├── StdioTransport.swift   - JSON-RPC stdio communication
│   ├── Logger.swift           - Thread-safe logging actor
│   ├── MCPMessages.swift      - MCP protocol message types
│   ├── MCPRequestHandler.swift - Request processing
│   ├── Errors.swift           - Error handling
│   └── ExampleClient.swift    - Usage examples
├── Package.swift              - Package manifest
└── README.md                  - This file

协议细节

• 沟通：通过TCP（主）或stdin/stdout（stdio模式）的JSON-RPC 2.0
• 格式：每个请求和响应都是一行以换行符结尾的JSON
• 时间戳：ISO8601格式
• 请求ID：始终包含一个独特的 id 领域
• 错误处理：错误遵循JSON-RPC 2.0错误规范

日志级别

建筑

关键组件

1. MCP服务器：协调服务器初始化
2. 标准运输：处理stdio上的JSON-RPC通信
3. MCP请求处理程序：处理传入的MCP请求
4. 日志记录器：线程安全参与者管理日志条目
5. 配置：解析和管理服务器配置

并发模型

• 使用Swift actors进行线程安全日志记录
• 异步/等待非阻塞操作
• 安全处理多线程访问

示例用法

启动服务器（TCP模式-默认）

swift run Log4MCP --log-level DEBUG --verbose
# Server listens on 0.0.0.0:3000

通过TCP发送请求（来自另一个终端）

使用 nc （netcat）：

# Log a message via TCP
echo '{"jsonrpc":"2.0","id":"1","method":"log.message","params":{"loggerId":"app","level":"INFO","message":"Test message"}}' | nc localhost 3000

使用Python客户端：

# Python TCP client example
import json
import socket

def send_request(method, params):
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    sock.connect(('localhost', 3000))

    request = {
        "jsonrpc": "2.0",
        "id": "1",
        "method": method,
        "params": params or {}
    }

    sock.send((json.dumps(request) + '\n').encode())
    response = sock.recv(4096).decode()
    sock.close()

    return json.loads(response)

# Log a message
response = send_request("log.message", {
    "loggerId": "myapp",
    "level": "INFO",
    "message": "Hello from Python"
})
print(response)

使用标准模式（MCP集成）

要使用stdio模式进行MCP集成，请执行以下操作：

swift run Log4MCP --stdio --log-level DEBUG --verbose

Stdio模式从stdin读取JSON-RPC请求并将响应写入stdout，使其适合与Claude和其他兼容MCP的客户端集成。

依赖项

• Swift NIO 2.56+用于高性能异步网络
• Swift异步算法 1.0+-用于异步序列算法
• Swift 6.2+编译器

发展

在调试模式下构建

swift build

运行测试

测试可以添加到 Tests/ 目录：

swift test

详细日志记录

启用详细输出以查看所有请求和响应：

swift run Log4MCP --verbose

演出

• 高效处理多个并发记录器
• 日志条目以可配置的轮换方式存储在内存中
• 支持高吞吐量日志记录场景

局限性

• 日志条目存储在内存中（不持久化到磁盘）
• 无内置群集或复制
• 单进程部署

未来的增强功能

• 基于文件的持久性
• 带有标签和元数据的结构化日志记录
• 内置过滤和搜索功能
• 指标和统计数据收集
• 与Claude AI环境集成

许可证

MIT许可证

贡献

欢迎投稿！请确保：

• 代码遵循Swift风格指南
• 所有代码构建都没有警告
• 新功能包括文档
• 更改保持了与MCP标准的向后兼容性

支持

有关问题、疑问或建议，请参阅MCP规范https://spec.modelcontextprotocol.io