@rulecatch/mcp-server 1.0.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +186 -0
  2. package/package.json +14 -2
package/README.md ADDED
@@ -0,0 +1,186 @@
1
+ # @rulecatch/mcp-server
2
+
3
+ MCP server for Rulecatch — query your rule violations, get fix plans, and review AI coding activity directly from Claude Code.
4
+
5
+ Works with [Model Context Protocol](https://modelcontextprotocol.io) (MCP). Connects to your Rulecatch dashboard data and exposes it as tools that Claude can call during your coding sessions.
6
+
7
+ **Requires a Pro or Enterprise plan.**
8
+
9
+ ## Quick Start
10
+
11
+ ### 1. Install hooks first (if you haven't already)
12
+
13
+ ```bash
14
+ npx @rulecatch/ai-pooler init
15
+ ```
16
+
17
+ This creates `~/.claude/rulecatch/config.json` with your API key and region. The MCP server reads the same config file.
18
+
19
+ ### 2. Add the MCP server to Claude Code
20
+
21
+ Add to your Claude Code MCP settings (`~/.claude/mcp.json`):
22
+
23
+ ```json
24
+ {
25
+ "mcpServers": {
26
+ "rulecatch": {
27
+ "command": "npx",
28
+ "args": ["-y", "@rulecatch/mcp-server"]
29
+ }
30
+ }
31
+ }
32
+ ```
33
+
34
+ That's it. Claude Code will now have access to 6 Rulecatch tools.
35
+
36
+ ## Tools
37
+
38
+ ### `rulecatch_summary`
39
+
40
+ Get an overview of violations and AI coding activity for a time period.
41
+
42
+ ```
43
+ "Show me my Rulecatch summary for the last 7 days"
44
+ ```
45
+
46
+ Returns: total violations, correction rate, estimated loss, session count, tool calls, cost, lines changed, top violated rules, and category breakdown.
47
+
48
+ | Parameter | Default | Options |
49
+ |-----------|---------|---------|
50
+ | `period` | `7d` | `today`, `3d`, `7d`, `14d`, `30d`, `this_week`, `this_month`, `all` |
51
+
52
+ ---
53
+
54
+ ### `rulecatch_violations`
55
+
56
+ List rule violations with filtering.
57
+
58
+ ```
59
+ "Show me all error-level violations from today"
60
+ ```
61
+
62
+ | Parameter | Description |
63
+ |-----------|-------------|
64
+ | `period` | Time period (default: `7d`) |
65
+ | `severity` | `error`, `warning`, or `info` |
66
+ | `category` | Rule category (e.g., `Security`, `Database Patterns`) |
67
+ | `corrected` | `true` or `false` |
68
+ | `rule` | Filter by rule name |
69
+ | `file` | File path pattern |
70
+ | `language` | Programming language |
71
+ | `toolName` | Tool that triggered the violation (`Write`, `Edit`, `Bash`) |
72
+ | `branch` | Git branch name |
73
+ | `sessionId` | Filter by specific AI session |
74
+ | `limit` | Max results (default: 20, max: 50) |
75
+
76
+ ---
77
+
78
+ ### `rulecatch_violation_detail`
79
+
80
+ Get full details for a specific violation — the matched rule, file location, conditions, git context, and fix guidance with code examples.
81
+
82
+ ```
83
+ "Show me details for violation abc123"
84
+ ```
85
+
86
+ | Parameter | Required | Description |
87
+ |-----------|----------|-------------|
88
+ | `id` | Yes | Violation ID from the violations list or fix plan |
89
+
90
+ Returns: rule name, description, severity, category, file path, line number, language, matched conditions, correction status, fix guide with wrong/correct code examples, and git context.
91
+
92
+ ---
93
+
94
+ ### `rulecatch_rules`
95
+
96
+ List all active rules with their conditions, severity, and descriptions.
97
+
98
+ ```
99
+ "What rules do I have configured?"
100
+ ```
101
+
102
+ No parameters. Returns all rules with their conditions, severity levels, categories, and enabled/disabled status.
103
+
104
+ ---
105
+
106
+ ### `rulecatch_fix_plan`
107
+
108
+ Get a file-by-file plan of uncorrected violations to fix, with estimated time and cost.
109
+
110
+ ```
111
+ "Generate a fix plan for all uncorrected errors"
112
+ ```
113
+
114
+ | Parameter | Description |
115
+ |-----------|-------------|
116
+ | `period` | Time period (default: `7d`) |
117
+ | `severity` | Filter by severity (default: errors + warnings) |
118
+ | `category` | Filter by category |
119
+ | `sessionId` | Fix violations from a specific session only |
120
+
121
+ Returns: grouped-by-file list of violations with line numbers, rule descriptions, fix guidance, wrong/correct code examples, and total estimated fix time and cost.
122
+
123
+ ---
124
+
125
+ ### `rulecatch_top_rules`
126
+
127
+ Get the most frequently violated rules, ranked by count.
128
+
129
+ ```
130
+ "Which rules am I breaking the most?"
131
+ ```
132
+
133
+ | Parameter | Description |
134
+ |-----------|-------------|
135
+ | `period` | Time period (default: `7d`) |
136
+ | `severity` | Filter by severity |
137
+ | `category` | Filter by category |
138
+ | `limit` | Max rules to return (default: 10, max: 25) |
139
+
140
+ Returns: ranked list with violation counts, correction rates, percentage of total, and category breakdown.
141
+
142
+ ## Architecture
143
+
144
+ ```
145
+ Claude Code
146
+ │
147
+ ▼
148
+ @rulecatch/mcp-server (runs locally via stdio)
149
+ │
150
+ ▼ HTTPS (Bearer token auth)
151
+ │
152
+ mcp.rulecatch.ai ─── MongoDB Atlas
153
+ ```
154
+
155
+ - The MCP server runs locally on your machine as a stdio process
156
+ - It reads your API key from `~/.claude/rulecatch/config.json`
157
+ - All requests go to `mcp.rulecatch.ai` (US) or `mcp-eu.rulecatch.ai` (EU)
158
+ - No code content is ever sent — only metadata queries
159
+
160
+ ## Requirements
161
+
162
+ - **Node.js** 18+
163
+ - **Rulecatch account** with Pro or Enterprise plan
164
+ - **Hooks configured** via `@rulecatch/ai-pooler init`
165
+
166
+ ## Troubleshooting
167
+
168
+ | Error | Cause | Fix |
169
+ |-------|-------|-----|
170
+ | `Rulecatch not configured` | Missing config file | Run `npx @rulecatch/ai-pooler init` |
171
+ | `Invalid API key` | API key doesn't match | Re-run `npx @rulecatch/ai-pooler init` |
172
+ | `MCP tools require a Pro or Enterprise plan` | Starter plan | Upgrade at dashboard |
173
+ | `Rate limited` | Too many requests | Wait a moment, try again |
174
+ | No tools appearing in Claude | MCP config not loaded | Restart Claude Code after editing `mcp.json` |
175
+
176
+ ## Links
177
+
178
+ - **Dashboard**: https://dashboard.rulecatch.ai?utm_source=npm&utm_medium=readme&utm_campaign=mcp-server&utm_content=links
179
+ - **Documentation**: https://rulecatch.ai/docs?utm_source=npm&utm_medium=readme&utm_campaign=mcp-server&utm_content=links
180
+ - **AI Pooler (hooks)**: https://www.npmjs.com/package/@rulecatch/ai-pooler
181
+ - **Privacy Policy**: https://rulecatch.ai/privacy?utm_source=npm&utm_medium=readme&utm_campaign=mcp-server&utm_content=links
182
+ - **GitHub**: https://github.com/TheDecipherist/rulecatch
183
+
184
+ ## License
185
+
186
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rulecatch/mcp-server",
3
- "version": "1.0.0",
3
+ "version": "1.1.1",
4
4
  "type": "module",
5
5
  "description": "Rulecatch MCP server - query violations and rules from Claude Code",
6
6
  "bin": {
@@ -22,5 +22,17 @@
22
22
  "tsx": "^4.0.0",
23
23
  "@types/node": "^20.0.0",
24
24
  "vitest": "^1.0.0"
25
- }
25
+ },
26
+ "license": "MIT",
27
+ "homepage": "https://rulecatch.ai",
28
+ "keywords": [
29
+ "rulecatch",
30
+ "mcp",
31
+ "model-context-protocol",
32
+ "claude",
33
+ "claude-code",
34
+ "ai-analytics",
35
+ "violations",
36
+ "rules"
37
+ ]
26
38
  }