🏠 本地日志记录器
一个以功能为先、具备生产级质量的本地日志记录系统，采用清晰的架构和双重接口。通过REST API写入日志，通过Cursor IDE中的MCP以美观的格式读取日志。
🎯 概述
Local Logger 为本地开发提供了一套完整的日志记录解决方案，包含两个相互补充的接口：
- 📝 写入接口应用程序用于发送结构化日志的REST API
- 📖 阅读界面用于Cursor IDE的MCP（模型上下文协议）工具，用于读取格式化日志叙述
🏗️ 建筑学
用……建造 以功能为先的模块化设计 并且 依赖注入 贯穿始终；整个过程
local_logger/
├── integration/ # Data persistence layer (JSON files)
├── models/ # Shared Pydantic schemas
├── write_log/ # Write feature (REST API)
│ ├── endpoint/ # FastAPI endpoints
│ └── orchestrator/ # Business logic
├── read_log/ # Read feature (MCP)
│ ├── endpoint/ # MCP server
│ └── orchestrator/ # Narrative formatting
├── data/logs/ # Log file storage
├── logs/ # Server logs
└── local_logger # Server management script设计原则
- 清洁架构端点、编排器和集成层之间的清晰分离
- 依赖注入易于测试和可替换的实现
- 特征隔离每个功能都是独立的，并带有自己的测试
- 测试驱动开发各层全面的测试覆盖
🚀 快速入门
1. 安装
# Clone or download the project
cd local_logger
# Install dependencies (Python 3.11 required)
pip3.11 install -r requirements.txt2. 启动服务器
# Start both servers (Write API + MCP)
./local_logger start
# Or simply
./local_logger3. 写你的第一条日志
curl -X POST http://127.0.0.1:8765/log \
-H "Content-Type: application/json" \
-d '{
"trace_id": "my-session-001",
"level": "INFO",
"message": "User logged in successfully",
"timestamp": "2025-10-05T12:00:00Z",
"data": {"user_id": 123, "ip": "192.168.1.1"}
}'4. 在Cursor中读取日志
使用MCP工具 read_logs_tool 与；和；带着 trace_id: "my-session-001" 获取；得到
Log History for trace_id: my-session-001
1. User logged in successfully
- user_id: 123
- ip: 192.168.1.1📊 服务器管理
这个（或“它”） local_logger 该脚本提供便捷的服务器管理功能：
./local_logger start # Start both servers (kills existing first)
./local_logger stop # Stop all servers
./local_logger restart # Restart servers (same as start)
./local_logger status # Check server status
./local_logger help # Show help服务器配置
- 写API：
http://127.0.0.1:8765(FastAPI 附带自动重载功能) - 读取MCP：
http://127.0.0.1:8766/sse(MCP通过HTTP) - 文档:
http://127.0.0.1:8765/docs - 日志：
logs/write_api.log和logs/mcp_server.log
📝 编写API使用方法
日志条目模式（或架构）
{
"trace_id": "string", // Required: Unique session/trace identifier
"level": "INFO", // Optional: DEBUG, INFO, WARN, ERROR
"message": "string", // Required: Log message
"timestamp": "2025-10-05T12:00:00Z", // Optional: ISO timestamp
"data": { // Optional: Structured metadata
"key": "value"
}
}示例
基本日志：
curl -X POST http://127.0.0.1:8765/log \
-H "Content-Type: application/json" \
-d '{"trace_id": "session-123", "message": "Process started"}'详细日志：
curl -X POST http://127.0.0.1:8765/log \
-H "Content-Type: application/json" \
-d '{
"trace_id": "debug-session",
"level": "ERROR",
"message": "Database connection failed",
"timestamp": "2025-10-05T12:30:00Z",
"data": {
"error_code": "DB_CONN_TIMEOUT",
"retry_count": 3,
"database": "users_db"
}
}'📖 读取接口（MCP）
Cursor IDE 集成
- 配置MCP 在里面
~/.cursor/mcp.json：
{
"mcpServers": {
"local_logger_mcp": {
"url": "http://127.0.0.1:8766/sse",
"enabled": true,
"name": "Local Logger MCP"
}
}
}- 重启光标 加载MCP服务器
- 使用这个工具
read_logs_tool带有参数：
- trace_id必需的字符串 - since可选的ISO时间戳过滤器 - limit可选数字（默认：200）
示例输出
输入： read_logs_tool(trace_id="debug-session")
输出：
Log History for trace_id: debug-session
1. Process started
- timestamp: 2025-10-05T12:00:00Z
2. User authentication successful
- user_id: 123
- method: oauth
- timestamp: 2025-10-05T12:15:00Z
3. Database connection failed
- error_code: DB_CONN_TIMEOUT
- retry_count: 3
- database: users_db
- timestamp: 2025-10-05T12:30:00Z🧪 测试
多层次的综合测试套件：
# Run all tests
python3.11 -m pytest -v
# Test specific layers
python3.11 -m pytest integration/tests/ -v # Integration layer
python3.11 -m pytest write_log/orchestrator/tests/ -v # Write orchestrator
python3.11 -m pytest read_log/orchestrator/tests/ -v # Read orchestrator
python3.11 -m pytest read_log/endpoint/tests/ -v # MCP endpoint测试理念
- 单元测试模拟依赖项，测试业务逻辑
- 集成测试使用临时目录进行实际文件输入/输出
- 端到端测试通过实际的API/MCP调用进行全系统测试
- 每个文件一个测试清晰、专注的测试组织
📁 数据存储
日志文件格式
日志以JSON数组的形式存储在 data/logs/{trace_id}.json:
[
{
"message": "User logged in successfully",
"timestamp": "2025-10-05T12:00:00Z",
"extras": {
"user_id": 123,
"ip": "192.168.1.1"
}
}
]关键特性
- 自动分类日志按时间戳顺序显示
- 灵活模式（或灵活架构）：
extras字段接受任何结构化数据 - “File-per-Trace”可以翻译为“每个追踪一个文件”。这个短语通常用于描述一种文件管理或追踪系统，其中每个追踪（或跟踪）操作或事件都会生成一个单独的文件每个
trace_id获得自己的JSON文件 - 人类可读格式化打印的JSON，便于调试
🔧 开发
项目结构
- 以特性为先每个特征（
write_log，read_log是自给自足的 - 依赖注入轻松模拟和测试
- 层分离端点 → 调度器 → 集成 → 存储
添加新功能
- 创建功能目录：
new_feature/ - 添加编排器：
new_feature/orchestrator/ - 添加终端节点：
new_feature/endpoint/ - 添加测试：
new_feature/*/tests/ - 遵循现有模式以保持一致性
依赖项
- FastAPI用于REST API的Web框架
- FastMCP模型上下文协议服务器
- Pydantic（发音类似“皮丹尼克”，但中文中通常直接音译为“Pydantic”或意译为“数据验证库”，具体根据上下文决定）数据验证和序列化
- Uvicorn（通常指一个用于运行ASGI应用的ASGI服务器，全称为“Uvicorn ASGI Server”，在中文语境下可直接称为“Uvicorn服务器”或根据具体上下文简化为“Uvicorn”）ASGI 服务器
- Pytest测试框架
🚨 故障排除
常见问题
服务器无法启动：
./local_logger status # Check current status
./local_logger stop # Force stop
./local_logger start # Clean start端口冲突：
- Write API使用8765端口
- MCP服务器使用8766端口
- 检查
local_logger修改端口的脚本
在Cursor中MCP不工作：
- 验证服务器是否正在运行：
./local_logger status - 检查MCP配置：
~/.cursor/mcp.json - 重启 Cursor IDE
- 检查服务器日志：
logs/mcp_server.log
导入错误：
- 确保使用的是 Python 3.11：
python3.11 --version - 安装依赖项：
pip3.11 install -r requirements.txt
日志记录和调试
- 服务器日志：
logs/write_api.log，logs/mcp_server.log - 数据文件：
data/logs/{trace_id}.json - 测试输出与……一起奔跑
-v用于详细输出的标志
🎯 使用场景
开发调试
import requests
# Log debug information
requests.post("http://127.0.0.1:8765/log", json={
"trace_id": "debug-session",
"message": "Variable state",
"data": {"user_count": 42, "memory_usage": "1.2GB"}
})
# Read in Cursor with read_logs_tool(trace_id="debug-session")应用程序监控
# Log application events
def log_event(trace_id, event, **data):
requests.post("http://127.0.0.1:8765/log", json={
"trace_id": trace_id,
"message": event,
"timestamp": datetime.utcnow().isoformat() + "Z",
"data": data
})
log_event("user-123", "Login successful", method="oauth", ip="192.168.1.1")
log_event("user-123", "Page viewed", page="/dashboard", load_time=1.2)测试与持续集成/持续交付（CI/CD）
# Log test results
curl -X POST http://127.0.0.1:8765/log \
-d '{"trace_id": "test-run-456", "message": "Test completed",
"data": {"passed": 42, "failed": 1, "duration": "2.3s"}}'
# Review in Cursor
# read_logs_tool(trace_id="test-run-456")📄 许可证
此项目专为本地开发使用而设计。请根据您的具体需求进行修改和扩展。
______________________________________________________________________
专为追求简洁、可测试日志记录及美观IDE集成的开发者打造，倾注爱心开发。