log-reader-mcp

v2.0.2

Published

5 months ago

![npm](https://img.shields.io/npm/v/log-reader-mcp) ![build](https://github.com/hassansaadfr/log-reader-mcp/actions/workflows/release.yml/badge.svg) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT

0High
0Medium
0Low

hassansaadfr

🚀 Log Reader Mcp

npm

🚀 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?

🤖 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

Install the package
```
npm install --save-dev log-reader-mcp
```
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:

| Use Case | Example Prompt to Cursor AI | | ------------------ | ----------------------------------------------------------- | | 🔢 Last N logs | Show me the last 100 log entries | | 🕒 Logs by time | Get all logs between 2024-06-01 and 2024-06-02 | | ⏩ Logs since date | Show all logs since 2024-06-01 | | 🚨 Errors only | Show only ERROR or CRITICAL logs from the last 50 entries | | 🔍 Search message | Find all logs containing "database connection failed" | | 🧑‍💻 User-specific | Show all logs for user_id 12345 in the last 24 hours | | 📊 Summary | Summarize the main issues found in today's logs | | 🧹 Clear context | Clear the log context and start a new analysis |

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

| Use Case | How Log Reader Mcp Helps | Time Saved | | ---------------------- | ----------------------------------------------------------- | ------------------ | | 🐞 Real-time debugging | See errors & warnings instantly in Cursor, with AI context | Minutes per bug | | 🔍 AI log analysis | Let the AI summarize, filter, and explain log events | Hours per incident | | 🚦 Incident response | Quickly surface critical issues to the whole team | Days per outage | | 👩‍💻 Onboarding | New devs get instant, readable log feedback in their editor | Weeks per new hire | | 📊 Audit & compliance | Structured logs, easy to export and review | Countless hours |

⚙️ 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

| Command | Effect | | --------------------------------- | --------------------------------------- | | npx log-reader-mcp init | Initialize MCP config and log workflow | | npx log-reader-mcp -h/--help | Show help and CLI options | | npx log-reader-mcp -v/--version | Show the current package version | | npx log-reader-mcp | Start the MCP log server (default mode) |

📝 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

Fork & create a branch
Use conventional commits
npm run build to compile
npm test to verify
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

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.
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 Cursor Rule Template for advanced configuration