{"_id":"@ailint/mcp","_rev":"3-2b6773c4f96c850817aef6eb9a594f65","name":"@ailint/mcp","dist-tags":{"latest":"2.0.1"},"versions":{"0.2.0":{"name":"@ailint/mcp","version":"0.2.0","keywords":["modelcontextprotocol","mcp","ailint","code-analysis","code-quality","ai-assistant"],"author":{"name":"Lucian Fialho"},"license":"MIT","_id":"@ailint/mcp@0.2.0","maintainers":[{"name":"lucianfialho","email":"lucian@metricasboss.com.br"}],"homepage":"https://github.com/lucianfialho/ailint#readme","bugs":{"url":"https://github.com/lucianfialho/ailint/issues"},"bin":{"ailint-mcp":"dist/index.js"},"dist":{"shasum":"1e6f693a66dd817d01fc4deef1e6f04d99ae0bd4","tarball":"https://registry.npmjs.org/@ailint/mcp/-/mcp-0.2.0.tgz","fileCount":16,"integrity":"sha512-GRxyUFsMrPtvhyvXYZC7h62moy2O6fRAumzaZCNC5R8Xmfayy5j8Rogj4DY4LZvZSn+wDYxDNfOIAbhC+8rr6A==","signatures":[{"sig":"MEQCIHaoPKWvukNhlCA58SuxTD8vqiE5LGtt+KSe3QnNcT28AiA8Y7MpIn15GiSnbI2LvHEG5IL3dw8tO8I03pJP64d1ig==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":113036},"type":"module","gitHead":"6308575803c5b6c058edafd49f58d3e7c0832362","scripts":{"dev":"npx tsx src/index.ts","lint":"eslint \"**/*.{js,ts,tsx}\" --fix","test":"echo \"Error: no test specified\" && exit 1","build":"tsc && chmod 755 dist/index.js","clean":"rm -rf dist","start":"node dist/index.js --transport stdio","format":"prettier --write .","prebuild":"npm run clean","lint:check":"eslint \"**/*.{js,ts,tsx}\""},"_npmUser":{"name":"lucianfialho","actor":{"name":"lucianfialho","type":"user","email":"lucian@metricasboss.com.br"},"email":"lucian@metricasboss.com.br"},"repository":{"url":"git+https://github.com/lucianfialho/ailint.git","type":"git"},"_npmVersion":"10.9.0","description":"AILint MCP Server - Intelligent code analysis for AI assistants","directories":{},"_nodeVersion":"22.12.0","dependencies":{"zod":"^3.24.2","js-yaml":"^4.1.0","commander":"^14.0.0","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.6.2","eslint":"^9.23.0","prettier":"^3.5.3","typescript":"^5.8.2","@types/node":"^22.13.14","@types/js-yaml":"^4.0.9","typescript-eslint":"^8.28.0","eslint-config-prettier":"^10.1.1","eslint-plugin-prettier":"^5.2.5","@typescript-eslint/parser":"^8.28.0","@typescript-eslint/eslint-plugin":"^8.28.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.2.0_1750597496466_0.8337255688415706","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@ailint/mcp","version":"2.0.0","keywords":["mcp","code-analysis","ai","quality","typescript"],"author":{"name":"AILint Team"},"license":"MIT","_id":"@ailint/mcp@2.0.0","maintainers":[{"name":"lucianfialho","email":"lucian@metricasboss.com.br"}],"bin":{"ailint":"dist/cli/index.js","ailint-mcp":"dist/server/index.js"},"dist":{"shasum":"fd61492e2aebe2f01dea3ed95cba48a63e91bd7d","tarball":"https://registry.npmjs.org/@ailint/mcp/-/mcp-2.0.0.tgz","fileCount":86,"integrity":"sha512-v5OqLx6vqMS7mmlKuGkEuTcAIuvVRE+xSqOE/uTRx0Nu8okn75cEAW7vjCmXP+p5Gw42H1vDM4iXLSFp67M6HA==","signatures":[{"sig":"MEUCIQC6Xv6PYbSmm4uhSzzzpDkKoYB0SqaL5LQ+HS1F0N/GYgIgZ/n+cB3zrqZ8eFulcYp/yXNzd9AsQcOOek60AgJLi3A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":266581},"type":"module","exports":{"./cli":"./dist/cli/index.js","./server":"./dist/server/index.js","./shared":"./dist/shared/index.js"},"gitHead":"95ccdc9486a0f90d0b89f0bb8fbde6a9d4e21989","scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsc","clean":"rm -rf dist","start":"node dist/server/index.js","dev:cli":"tsx src/cli/index.ts","dev:server":"tsx src/server/index.ts"},"_npmUser":{"name":"lucianfialho","actor":{"name":"lucianfialho","type":"user","email":"lucian@metricasboss.com.br"},"email":"lucian@metricasboss.com.br"},"_npmVersion":"10.9.0","description":"AILint MCP Server - AI-powered code quality analysis","directories":{},"_nodeVersion":"22.12.0","dependencies":{"zod":"^3.22.0","commander":"^11.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_2.0.0_1751221188620_0.028791915728336503","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@ailint/mcp","version":"2.0.1","description":"AILint MCP Server - AI-powered code quality analysis","type":"module","exports":{"./server":"./dist/server/index.js","./cli":"./dist/cli/index.js","./shared":"./dist/shared/index.js"},"bin":{"ailint":"dist/cli/index.js","ailint-mcp":"dist/server/index.js"},"scripts":{"build":"tsc","dev:server":"tsx src/server/index.ts","dev:cli":"tsx src/cli/index.ts","start":"node dist/server/index.js","test":"echo \"Error: no test specified\" && exit 1","clean":"rm -rf dist"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","commander":"^11.0.0","zod":"^3.22.0"},"devDependencies":{"@types/node":"^20.0.0","tsx":"^4.0.0","typescript":"^5.0.0"},"keywords":["mcp","code-analysis","ai","quality","typescript"],"author":{"name":"AILint Team"},"license":"MIT","_id":"@ailint/mcp@2.0.1","gitHead":"2d0138d39f3b79dc669ee1a24aa7451e1e6d111a","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-kptSuCpVN4zENslHLZYLNdYOd7m80W1yZsY2tnCpFUhs5Efewgf93YOzvKCgN8u3X0nuxz44iXNHyVnF5Y/yJg==","shasum":"a07a91b4bf04393b642d3675c56034762606e422","tarball":"https://registry.npmjs.org/@ailint/mcp/-/mcp-2.0.1.tgz","fileCount":86,"unpackedSize":266498,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDgYNbZkjIxx68avYwzbKYNbppYFopua7zWSgkLmj4z2AIhAPa5lxOrIKl8Q82KcWlTrukXr3DS8DH/5Qqyati4SsNl"}]},"_npmUser":{"name":"lucianfialho","email":"lucian@metricasboss.com.br","actor":{"name":"lucianfialho","email":"lucian@metricasboss.com.br","type":"user"}},"directories":{},"maintainers":[{"name":"lucianfialho","email":"lucian@metricasboss.com.br"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_2.0.1_1751222733256_0.3915444652211597"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-22T13:04:56.366Z","modified":"2025-06-29T18:45:33.661Z","0.2.0":"2025-06-22T13:04:56.650Z","2.0.0":"2025-06-29T18:19:48.811Z","2.0.1":"2025-06-29T18:45:33.481Z"},"author":{"name":"AILint Team"},"license":"MIT","keywords":["mcp","code-analysis","ai","quality","typescript"],"description":"AILint MCP Server - AI-powered code quality analysis","maintainers":[{"name":"lucianfialho","email":"lucian@metricasboss.com.br"}],"readme":"# AILint: Constraint Rules for AI Code Generation\n\n**Stop AI from generating problematic code – Enforce software engineering principles.**\n\n> **The Problem**: AI assistants are incredible at generating functional code, but they often produce code that violates best practices, security principles, and architectural patterns. This leads to technical debt, security vulnerabilities, and maintainability nightmares.\n>\n> **The Solution**: AILint provides a set of deterministic state machine rules that act as \"guardrails\" for AI code generation. By applying proven software engineering principles as constraints *during* the code generation process, AILint ensures the output is high-quality, secure, and maintainable.\n\n## Why AILint?\n\nAI assistants, while powerful, frequently exhibit common pitfalls in code generation:\n- **Tightly Coupled & Untestable Code**: Defaults to hardcoded dependencies and monolithic structures.\n- **Insecure Patterns**: Introduces SQL injection vulnerabilities, weak cryptography, and other security flaws.\n- **Unreadable & Complex Code**: Generates deeply nested logic and vague naming conventions.\n- **Inefficient Operations**: Uses blocking calls instead of asynchronous, concurrent patterns.\n- **Inconsistent Practices**: Produces non-standard commit messages, unhelpful error messages, and generic variable/function names.\n\n**AILint solves these issues by applying constraints *during* the code generation process, not just after.**\n\n## How It Works\n\nEach AILint rule is a sophisticated **state machine** designed to guide AI behavior:\n\n1.  **Detection**: Identifies problematic patterns or anti-patterns in AI requests or generated code snippets.\n2.  **Analysis**: Evaluates the context, intent, and potential implications of the detected pattern.\n3.  **Constraint**: Applies specific architectural principles, security best practices, or code quality standards as constraints.\n4.  **Validation**: Ensures the AI's output adheres to these constraints, providing feedback if violations occur.\n\n```\nAI Request → Detection → Analysis → Constraint → Validation → High-Quality Code\n```\n\n## Universal Rules\n\nAILint's core strength lies in its universal rules, which are language-agnostic and apply fundamental software engineering principles. These rules are defined in `.mdc` files within the `rules/universal/` directory.\n\n### **Architecture & Design**\n- **[avoid-god-classes](rules/universal/avoid-god-classes.mdc)**: Prevents AI from creating massive, multi-responsibility classes, enforcing the Single Responsibility Principle.\n- **[composition-over-inheritance](rules/universal/composition-over-inheritance.mdc)**: Guides AI to favor composition for flexible, testable designs over rigid inheritance hierarchies.\n- **[dependency-injection](rules/universal/dependency-injection.mdc)**: Ensures AI generates code with proper dependency injection, promoting testability and loose coupling.\n\n### **Security & Performance**\n- **[secure-by-default](rules/universal/secure-by-default.mdc)**: Enforces security-first patterns, preventing SQL injection, weak cryptography, and other common vulnerabilities.\n- **[promise-patterns](rules/universal/promise-patterns.mdc)**: Guides AI to use concurrent asynchronous patterns, eliminating blocking operations and improving performance.\n\n### **Code Quality & Readability**\n- **[prefer-early-returns](rules/universal/prefer-early-returns.mdc)**: Eliminates deeply nested if-else chains by enforcing guard clauses and early return patterns.\n- **[conventional-commits](rules/universal/conventional-commits.mdc)**: Ensures AI generates clear, structured commit messages following the Conventional Commits standard.\n- **[descriptive-function-names](rules/universal/descriptive-function-names.mdc)**: Prevents vague function names (`process`, `handle`) by enforcing intention-revealing, behavior-specific naming.\n- **[explicit-error-messages](rules/universal/explicit-error-messages.mdc)**: Guides AI to generate specific, actionable error messages instead of generic, unhelpful ones.\n- **[meaningful-variable-names](rules/universal/meaningful-variable-names.mdc)**: Eliminates vague variable names (`data`, `result`) by enforcing intention-revealing, context-specific naming.\n\n## Before vs After\n\nSee the dramatic improvement in AI-generated code when AILint's constraints are applied.\n\n### **Without AILint** (what AI typically generates):\n\n```python\n# Tightly coupled, insecure, unreadable nightmare\nclass UserService:\n    def __init__(self):\n        self.db = PostgresDatabase(\"localhost:5432\")  # Hardcoded!\n        self.cache = RedisCache(\"localhost:6379\")     # Untestable!\n    \n    def login(self, username, password):\n        # SQL injection vulnerability\n        query = f\"SELECT * FROM users WHERE username = '{username}'\"\n        user = self.db.execute(query).fetchone()\n        \n        # Weak password hashing\n        password_hash = hashlib.md5(password.encode()).hexdigest()\n        \n        if user:\n            if user.get('is_active'):\n                if user.get('email'):\n                    if '@' in user['email']:\n                        if user.get('has_permission'):\n                            # Logic buried 5 levels deep!\n                            return user['email'].lower()\n```\n\n### **With AILint** (constrained generation):\n\n```python\n# Loosely coupled, secure, testable, and readable\nclass UserService:\n    def __init__(self, db, cache, logger):\n        # Dependencies injected - fully testable!\n        self.db = db\n        self.cache = cache\n        self.logger = logger\n    \n    def login(self, username, password):\n        # Guard clauses - fail fast, clear flow\n        if not username:\n            raise ValueError('Username required')\n        if not password:\n            raise ValueError('Password required')\n        \n        # Parameterized query - SQL injection impossible\n        query = \"SELECT * FROM users WHERE username = ?\"\n        user = self.db.execute(query, (username,)).fetchone()\n        \n        # Secure password verification with bcrypt\n        if user and bcrypt.checkpw(password.encode(), user['password_hash']):\n            self.logger.info(f\"User {username} logged in successfully\")\n            return user\n        \n        raise AuthenticationError('Invalid credentials')\n```\n\n## Quick Start\n\n### **Copy-Paste Method** (Immediate Use)\nFor quick, ad-hoc application of rules:\n1.  **Choose a rule** from the `rules/universal/` directory (e.g., `secure-by-default.mdc`).\n2.  **Copy the entire content** of the `.mdc` file.\n3.  **Paste the rule content** directly into your AI assistant's prompt *before* your code generation request.\n4.  **Generate code** – the AI will automatically follow the constraints!\n\n**Example**: To prevent hardcoded dependencies, copy the content of `dependency-injection.mdc` into your prompt.\n\n### **MCP Integration** (Professional Setup)\nFor seamless, persistent integration with AI tools like Claude, Cursor, and others, use the AILint MCP (Model Context Protocol) server. This project (`ailint-mcp`) provides the server implementation.\n\n```bash\nnpm install -g @ailint/mcp\n```\n\nSee the [ailint-mcp repository](https://github.com/lucianfialho/ailint-mcp) for detailed setup instructions for various IDEs and AI clients.\n\n## Repository Structure\n\n```\nailint/\n├── rules/\n│   ├── universal/              # Language-agnostic rules (e.g., SRP, Security, Naming)\n│   │   ├── avoid-god-classes.mdc\n│   │   ├── composition-over-inheritance.mdc\n│   │   ├── conventional-commits.mdc\n│   │   ├── dependency-injection.mdc\n│   │   ├── descriptive-function-names.mdc\n│   │   ├── explicit-error-messages.mdc\n│   │   ├── meaningful-variable-names.mdc\n│   │   ├── prefer-early-returns.mdc\n│   │   ├── promise-patterns.mdc\n│   │   └── secure-by-default.mdc\n│   ├── language-specific/      # (Future) Rules for specific languages (e.g., Python, JS, Java)\n│   └── framework-specific/     # (Future) Rules for specific frameworks (e.g., React, Spring)\n├── schemas/                    # (Future) Schemas for rule validation\n│   └── rule-schema.json\n├── docs/                       # (Future) Documentation on writing rules, philosophy\n│   └── writing-rules.md\n├── .gitignore\n└── README.md                   # This file\n```\n\n## Language Support\n\nAILint rules are designed to be universal, but examples and adaptations are provided for clarity across different programming languages:\n\n-   **Python**: Primary examples, focusing on idiomatic Python patterns.\n-   **JavaScript**: ES6+ patterns, Promise-based async, modern module practices.\n-   **Java**: Enterprise patterns, `CompletableFuture`, Spring conventions.\n-   **C#**: .NET patterns, `Task.WhenAll`, secure coding practices.\n\n## Contributing\n\nWe welcome contributions to expand AILint's rule set and improve its effectiveness!\n\n### **Adding New Rules**\n\n1.  **Identify an AI limitation**: Pinpoint a common problematic pattern AI generates (e.g., \"AI generates synchronous code when async is better\").\n2.  **Create a rule file**: Add a new `.mdc` file in `rules/universal/` (or a new language/framework directory if applicable).\n3.  **Define the state machine**: Structure your rule with `triggers`, `states`, `transitions`, and `actions` as demonstrated in existing `.mdc` files.\n4.  **Include clear examples**: Provide \"bad\" (AI-generated without AILint) and \"good\" (AI-generated with AILint) code examples.\n5.  **Submit a Pull Request**: Ensure your commit message follows Conventional Commits.\n\n### **Improving Existing Rules**\n\n-   Add language-specific adaptations or more diverse examples.\n-   Refine rule descriptions, triggers, or constraints.\n-   Optimize state machine logic for better detection.\n\n### **Reporting Issues**\n\n-   **Bug reports**: Describe unexpected AI behavior or rule failures with reproducible examples.\n-   **Feature requests**: Suggest new rules or enhancements to the AILint system.\n-   **Documentation**: Help improve clarity, examples, and guides.\n\n\n\n## Roadmap\n\n-   [ ] **Phase 3 (Planned)**:\n    -   **AST-based Analysis**: Implement deeper, more accurate code analysis.\n    -   **Custom Rule Creation UI**: A user-friendly interface for defining new rules.\n    -   **Rule Marketplace**: A platform for sharing and discovering community-contributed rules.\n    -   **Team Analytics & Dashboards**: Insights into code quality trends over time.\n    -   **VS Code Extension**: Direct integration into the VS Code editor.\n-   [ ] **Future Enhancements**:\n    -   Language-specific rule packs (e.g., Python, JavaScript, Java).\n    -   Framework-specific rule packs (e.g., React, Spring, Django).\n    -   Integration APIs for popular AI coding assistants.\n\n## Philosophy\n\nAILint is built on the principle that **constraints enable creativity**. By providing AI assistants with clear, well-defined boundaries based on proven software engineering principles, we empower them to generate not just functional code, but *excellent* code.\n\nThink of it as **\"guardrails that prevent AI from generating problematic code\"** – keeping AI on the path to quality, security, and maintainability.\n\n## License\n\nThis project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.\n\n## Community\n\n-   **GitHub Issues**: [Report bugs or request features](https://github.com/lucianfialho/ailint/issues)\n-   **Discussions**: [Share ideas, ask questions, and collaborate](https://github.com/lucianfialho/ailint/discussions)\n-   **Twitter**: Follow [@ailint_dev](https://twitter.com/ailint_dev) for updates\n\n---\n\n**Built with ❤️ by developers who are tired of AI generating problematic code.**\n\n> *\"Stop the problematic code epidemic – one AI constraint at a time\"* – AILint Team\n","readmeFilename":"README.md"}