{"id":46705992,"url":"https://github.com/pppp606/claude-ops-mcp","last_synced_at":"2026-03-09T08:11:32.219Z","repository":{"id":314562989,"uuid":"1054537920","full_name":"pppp606/claude-ops-mcp","owner":"pppp606","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-07T13:50:49.000Z","size":271,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-08T14:22:07.954Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pppp606.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-11T01:45:37.000Z","updated_at":"2025-10-07T12:46:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"e6b676f8-74e8-4f25-a7af-e2c1361fa01e","html_url":"https://github.com/pppp606/claude-ops-mcp","commit_stats":null,"previous_names":["pppp606/claude-ops-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/pppp606/claude-ops-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pppp606%2Fclaude-ops-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pppp606%2Fclaude-ops-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pppp606%2Fclaude-ops-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pppp606%2Fclaude-ops-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pppp606","download_url":"https://codeload.github.com/pppp606/claude-ops-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pppp606%2Fclaude-ops-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30287501,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-09T08:11:31.620Z","updated_at":"2026-03-09T08:11:32.204Z","avatar_url":"https://github.com/pppp606.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-ops-mcp\n\nMCP server that indexes Claude Code operation history (file edits/writes, Bash runs, reads) from local Claude Desktop logs and exposes it as queryable tools. Designed to help agents inspect what happened, generate diffs, and assist with rollback or failure analysis.\n\nStatus: early preview. Available on npm.\n\n## Features\n\n- Operation history indexing: parses Claude Code JSONL session logs under `~/.claude/projects/*`.\n- File-change queries: list recent creates/updates/deletes for any file or glob-like pattern.\n- Bash history: list commands with summaries, then drill down to stdout/stderr details.\n- Diff views: retrieve detailed diffs for Edit/Write/MultiEdit operations in a unified format.\n- Session discovery: automatically locates the active session via Claude’s tool-use metadata.\n- MCP-first: communicates over stdio and advertises tools via the Model Context Protocol.\n\n## How It Works\n\n- Claude Code writes session logs per project at `~/.claude/projects/\u003cprojectHash\u003e/\u003csessionId\u003e.jsonl`.\n- When this server initializes, it emits a session UID and can later resolve the correct session using the tool-use id (`_meta[\"claudecode/toolUseId\"]`) that Claude passes to MCP tools.\n- Handlers parse the JSONL log stream, map operations to a compact index (`OperationIndex`), and provide detailed diffs on demand.\n- Supported MCP protocol version: `2024-11-05`.\n\n## Requirements\n\n- Node.js \u003e= 18\n- Claude Code (or another MCP client) running on the same machine\n\n## Installation\n\nFrom npm (recommended):\n\n```bash\nnpm install -g claude-ops-mcp\n```\n\nFrom source:\n\n```bash\ngit clone https://github.com/pppp606/claude-ops-mcp.git\ncd claude-ops-mcp\nnpm ci\nnpm run build\n```\n\n## Configure With Claude Code\n\nOption A — after global npm install:\n\n```json\n{\n  \"mcpServers\": {\n    \"claude-ops-mcp\": {\n      \"command\": \"claude-ops-mcp\",\n      \"args\": [],\n      \"env\": {}\n    }\n  }\n}\n```\n\nOption B — from source (for development):\n\n```json\n{\n  \"mcpServers\": {\n    \"claude-ops-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/claude-ops-mcp/dist/index.js\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\nPlace the JSON into Claude Code's `.mcp.json` configuration file in your project root. See the [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp) for details. A minimal example is also provided in `.mcp.example.json`.\n\n## Available Tools\n\nThe server advertises these tools via MCP’s `list_tools`:\n\n1) `listFileChanges`\n- Input: `{ filePath: string, limit?: number }`\n- Returns: recent non-READ file operations (CREATE/UPDATE/DELETE) matching the path or pattern.\n\nExample response:\n\n```json\n{\n  \"operations\": [\n    {\n      \"id\": \"toolu_01UGt...\",\n      \"timestamp\": \"2025-01-01T12:34:56.789Z\",\n      \"tool\": \"Edit\",\n      \"filePath\": \"/path/to/project/src/index.ts\",\n      \"summary\": \"Edit operation on /path/to/project/src/index.ts\",\n      \"changeType\": \"update\"\n    }\n  ],\n  \"totalCount\": 1,\n  \"hasMore\": false,\n  \"limit\": 100,\n  \"filePath\": \"src/index.ts\"\n}\n```\n\n2) `listBashHistory`\n- Input: `{ limit?: number }`\n- Returns: recent Bash commands with concise summaries.\n\nExample response:\n\n```json\n{\n  \"commands\": [\n    {\n      \"id\": \"toolu_01Vabc...\",\n      \"timestamp\": \"2025-01-01T12:35:01.000Z\",\n      \"command\": \"npm test\",\n      \"exitCode\": 0,\n      \"workingDirectory\": \"/path/to/project\",\n      \"summary\": \"PASS src/foo.test.ts\"\n    }\n  ],\n  \"totalCount\": 3,\n  \"hasMore\": false,\n  \"limit\": 100\n}\n```\n\n3) `showBashResult`\n- Input: `{ id: string }` (use an id returned by `listBashHistory`)\n- Returns: stdout/stderr and exit code for the specific Bash operation.\n\nExample response:\n\n```json\n{\n  \"id\": \"toolu_01Vabc...\",\n  \"timestamp\": \"2025-01-01T12:35:01.000Z\",\n  \"command\": \"npm test\",\n  \"exitCode\": 0,\n  \"workingDirectory\": \"/path/to/project\",\n  \"stdout\": \"PASS src/foo.test.ts\\n...\",\n  \"stderr\": \"\"\n}\n```\n\n4) `showOperationDiff`\n- Input: `{ id: string }` (use an id returned by `listFileChanges` or `listBashHistory`)\n- Returns: tool-specific diff details. For Edit/Write/MultiEdit, includes `oldString`, `newString`, and a unified diff; for Bash, includes `stdout`, `stderr`, and `exitCode`.\n\nExample (Edit/Write style):\n\n```json\n{\n  \"id\": \"toolu_01UGt...\",\n  \"timestamp\": \"2025-01-01T12:34:56.789Z\",\n  \"tool\": \"Edit\",\n  \"filePath\": \"/path/to/project/src/index.ts\",\n  \"diff\": {\n    \"oldString\": \"console.log('old')\",\n    \"newString\": \"console.log('new')\",\n    \"unified\": \"--- /path/to/project/src/index.ts\\n+++ /path/to/project/src/index.ts\\n- console.log('old')\\n+ console.log('new')\\n\"\n  },\n  \"_debug\": {\n    \"hasToolResult\": true\n  }\n}\n```\n\n## Notes on Session Discovery\n\n- Primary path: the server expects Claude to pass `_meta[\"claudecode/toolUseId\"]` with each tool call; it uses this to find the active session file and caches it for subsequent calls.\n- Fallbacks: the server can also discover the most recent session for the current project path, but toolUseId-based discovery is the most reliable.\n- Cache: discovery results are cached in-memory; tune TTL with `CLAUDE_OPS_CACHE_TTL_MS` (milliseconds).\n\n## Environment Variables\n\n- `CLAUDE_OPS_CACHE_TTL_MS`: override the session discovery cache TTL in milliseconds.\n\n## Development\n\nScripts:\n\n```bash\nnpm run dev          # run with tsx (stdio MCP)\nnpm run build        # compile to dist/\nnpm test             # run Jest tests\nnpm run lint         # eslint\nnpm run format       # prettier\nnpm run ci           # typecheck + lint + coverage + build\n```\n\nLocal MCP config examples:\n\n- `.mcp.example.json` (Claude Code / generic MCP client)\n- `claude_desktop_config.example.json` (for reference only)\n\n## Dependency Management\n\nThis repository consolidates dependency updates and security checks to keep CI signal clean:\n\n- Weekly npm updates: single PR grouping all patch/minor updates; majors ignored by default\n- Monthly GitHub Actions updates: single PR grouping all actions\n- PR-time Dependency Review: blocks introducing known vulnerabilities (requires Dependency graph enabled)\n- CI `npm audit`: production dependencies only, threshold `moderate`\n\nSee `docs/dependency-management.md` for details and how to adjust thresholds and schedules.\n\n## Roadmap\n\nThis project targets the goals described in issue #1:\n\n- MCP server foundation, session log identification via UID/toolUseId\n- Operation index API and detailed diff API\n- File change and Bash history APIs with unified diff format\n- Future: rollback helpers, performance tuning, security hardening\n\n## Security and Privacy\n\n- Reads local Claude logs only; does not send data to external services.\n- Standard file access permissions apply; no elevated privileges are required.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpppp606%2Fclaude-ops-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpppp606%2Fclaude-ops-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpppp606%2Fclaude-ops-mcp/lists"}