hassansaadfr/log-reader-mcp

🚀 Log Reader Mcp

🚀 Stop wasting time copy-pasting logs!
🧠 Let Cursor's AI instantly access, search, and explain your logs — no more manual work, just answers.

📚 Table of Contents

• Why Log Reader Mcp?
• Installation
  • Automatic (recommended)
  • Manual
• Who is it for?
• MCP Configuration
• Example Prompts for Cursor
• CLI Usage
• Log Format (JSON per line)
• Developer Guide
• Key Advantages
• FAQ
• Getting Help
• Contributing
• License
• Cursor Rule (Workflow)

✨ Why Log Reader Mcp?

• 🤖 AI-powered log access: Give your AI assistant (Cursor, etc.) direct, on-demand access to your app logs.
• 🧠 Smarter debugging: Let the AI analyze, summarize, and explain logs as you code.
• ⏱️ Save hours: No more switching terminals, tailing files, or hunting for errors—get instant feedback and context.
• 🛡️ Safe & isolated: Never pollutes your project, robust CLI and test coverage.
• ⚡ Plug & Play: One command, zero config, works everywhere.

👤 Who is it for?

• Backend & frontend developers
• DevOps & SREs
• Teams using AI-powered editors (Cursor, etc.)
• Anyone who wants faster, smarter log analysis!

📦 Installation

🚀 Automatic (recommended)

npx log-reader-mcp init

• Installs everything, creates .cursor/mcp.json and workflow rules, and sets up your logs folder automatically.

🛠️ Manual

1. Install the package

   npm install --save-dev log-reader-mcp
   

2. Create the config file

   • At the root of your project, create a folder named .cursor (if it doesn't exist).
   • Inside .cursor/, create a file named mcp.json with:

   {
     "mcpServers": {
       "log-reader-mcp": {
         "command": "npx",
         "args": ["-y", "log-reader-mcp"]
       }
     },
     "mcp.enabled": true,
     "mcp.autoStart": true,
     "mcp.showStatusBar": true,
     "mcp.logLevel": "info"
   }
   

   • This tells your editor (Cursor, VSCode, etc.) how to launch and connect to the log reader mcp server for your project.

🖼️ What does it do?

Log Reader Mcp exposes your application's logs to your AI assistant/editor (like Cursor) via the Model Control Protocol (MCP). This means:

• The AI can read, filter, and analyze your logs on demand (not streaming)
• You can ask the AI to fetch logs for a specific period, number of lines, error level, etc.
• Makes onboarding, debugging, and incident response dramatically faster

🔧 Key Features

• Simplified Interface: No logPath parameter needed - always uses logs/logs.log in your working directory
• Automatic Detection: The server automatically finds and reads your log file
• Time-based Filtering: Filter logs by specific time ranges using ISO 8601 format
• Line-based Reading: Read the last N lines with automatic validation
• Structured JSON: Full support for structured logging with metadata

💡 Example Prompts for Cursor

Here are some real-world prompts you can use in Cursor (or any MCP-enabled AI) to interact with your logs:

Note: The tool automatically uses logs/logs.log in your current working directory. The logPath parameter has been removed for maximum simplicity - no need to specify any file path!

Tip: You can combine filters, time ranges, and keywords in your prompts. The AI will use Log Reader Mcp to fetch and analyze the relevant log data for you!

💡 Use Cases

⚙️ MCP Configuration Example

{
  "mcpServers": {
    "log-reader-mcp": {
      "command": "npx",
      "args": ["-y", "log-reader-mcp"]
    }
  },
  "mcp.enabled": true,
  "mcp.autoStart": true,
  "mcp.showStatusBar": true,
  "mcp.logLevel": "info"
}

• 📁 Place this in .cursor/mcp.json
• Your editor will auto-detect and use the log server

🖥️ CLI Usage

📝 Log Format (JSON per line)

Each line in logs/logs.log should be a JSON object:

{
  "level": "INFO|WARN|ERROR|DEBUG|CRITICAL",
  "timestamp": "2024-06-01T12:34:56.789Z",
  "message": "User login succeeded",
  "service_name": "auth",
  "user_id": "12345",
  "context": { "ip": "192.168.1.10" },
  "event": { "action": "login" }
}

🧑‍💻 Developer Guide

• Release & Versioning: Automated with semantic-release, changelog, and version auto-sync
• CI/CD: GitHub Actions (.github/workflows/)
• Testing: 100% coverage, CLI test isolation, robust integration
• Project Structure:
  • src/ — TypeScript sources
  • bin/cli.js — CLI entry point
  • templates/ — MCP config & workflow templates
  • .github/workflows/ — CI/CD

🏆 Key Advantages

• 🔒 Zero config, zero risk: Never pollutes your project
• 🧪 100% tested: Full test isolation, robust CI
• 🏗️ AI-ready: Structured logs, perfect for automated analysis
• 🚀 Plug & Play: Works with all MCP editors, no setup required
• ⏳ Massive time savings: Focus on code, not on chasing logs

🤝 Contributing

1. Fork & create a branch
2. Use conventional commits
3. npm run build to compile
4. npm test to verify
5. Open a clear, detailed PR

📄 License

MIT

📝 Cursor Rule (Workflow)

To help Cursor (or any MCP-compatible AI) understand your log structure and best practices, you can add a workflow rule file:

How to add the Cursor rule

1. Copy the template

   • Use the command: npx log-reader-mcp init (recommended)
   • Or manually copy templates/mcp-log-server/workflow.mdc to .cursor/log-reader-mcp/workflow.mdc at the root of your project.

2. What does this rule do?

   • It describes the log file location, format, and usage standards for your project.
   • It helps the AI agent (Cursor, etc.) understand how to read, filter, and analyze your logs.
   • It documents best practices for logging, security, and debugging for your team.

Example (excerpt)

---
description: Guide for using log-reader-mcp
globs: **/*
alwaysApply: true
---

# MCP Logging Workflow

- Log folder: `logs/`
- Log file: `logs.log` (one JSON object per line)
- Example log entry:

  {
    "level": "INFO",
    "timestamp": "2024-06-01T12:34:56.789Z",
    "message": "User login succeeded",
    ...
  }

- Use the `read_log` tool to fetch logs by line count or time range
- Never include sensitive data in logs
- Always validate log format before writing

Why add this rule?

• 🧠 For the AI: It enables Cursor to provide smarter, context-aware log analysis and suggestions.
• 👩‍💻 For developers: It ensures everyone follows the same standards and makes onboarding easier.
• 🔒 For security: It reminds everyone not to log sensitive data and to validate log structure.

Tip: Keeping this rule up to date helps both humans and AI work better with your logs!

❓ FAQ

Q: Is it compatible with VSCode or only Cursor?
A: Any editor supporting MCP can use it, including Cursor and future tools.

Q: Can I use multiple MCP servers?
A: Yes, just add more entries in .cursor/mcp.json.

Q: What log formats are supported?
A: Only structured JSON logs (one object per line) are supported for full AI analysis.

Q: Is it safe for production?
A: Yes! The tool never modifies your logs, only reads them, and is fully tested.

💬 Getting Help

• Open an issue for bugs or questions
• Join the discussion on GitHub Discussions
• See the for advanced configuration