@janreges/ai-distiller-mcp
Advanced tools
AI Distiller (aid) - Essential code structure extractor for LLMs. Provides AI with accurate code signatures, data types, and API contracts from your actual codebase, reducing guesswork and trial-error coding. Accelerates analysis workflows including secur
When coding with AI (vibe coding), the biggest challenge is understanding existing code. AI assistants often write broken code on the first attempt and need multiple iterations to fix it. Why? Because they don't know the actual APIs, data types, and contracts in your codebase.
To save context, AI agents prefer searching/grepping code and showing only a few lines around matches. This approach is slow, often misses relevant information, and provides incomplete understanding of code structure and relationships.
AI Distiller solves this by extracting complete, precise code structure instantly. Simply tell your AI: "Distill and study the public interfaces from ./src/components" - and watch your AI write correct code on the first try!
AI Distiller MCP server uses AI Distiller - Essential code structure extractor that provides LLMs with accurate code signatures, data types, and API contracts from your actual codebase.
Note: This is the very first version of this tool. We would be very grateful for any feedback in the form of a discussion or by creating an issue on GitHub. Thank you!
Extract essential code structure from files/directories to provide AI with accurate API signatures, types, and contracts. This dramatically improves AI's understanding of your codebase and leads to more accurate code generation.
Example: "Distill ./src/components to understand the component APIs before we modify them"
Generate specialized analysis prompts and workflows that guide AI agents through comprehensive code analysis tasks like security audits, refactoring suggestions, or documentation generation.
Example: "Use aid to analyze security vulnerabilities in ./api" or "Generate refactoring suggestions for ./legacy"
⚠️ IMPORTANT for AI Actions: AI Distiller generates analysis prompts with distilled code - it does NOT perform the actual analysis! The output is a specialized prompt + distilled code that AI agents (like Claude Code, Cursor) or users can execute. For large codebases, you can copy the output to tools like Gemini 2.5 with 1M context window.
💡 NOTE: When using AI actions, AI Distiller tries to instruct the AI agent to execute the prompt and analysis immediately after generation. However, the AI agent may or may not follow this instruction automatically. If the analysis doesn't start automatically, simply ask your AI agent to "execute the generated prompt" or "perform the analysis from the aid output".
This is the first version of this tool and its possibilities of use are very extensive. Apply it to your use-cases, be playful and inventive, and send any bugs or feature requests to GitHub issues. We'll be implementing more useful features in future versions. One of them is the possibility to define your own API token to Gemini or ChatGPT/Claude and let external LLM perform the analysis itself. MCPs have relatively low limits on I/O size and using external LLMs via API would bring additional benefits.
# Install for current project only
claude mcp add aid -- npx -y @janreges/ai-distiller-mcp
# Install globally for all projects
claude mcp add --scope=user aid -- npx -y @janreges/ai-distiller-mcp
⚠️ Important for user-wide installation:
You must set AID_ROOT environment variable in your Claude Code configuration to point to your current project directory. Without this, the aid tool won't know which directory to analyze.
Example configuration:
{
"mcpServers": {
"aid": {
"command": "npx",
"args": ["-y", "@janreges/ai-distiller-mcp"],
"env": {
"AID_ROOT": "/absolute/path/to/your/project"
}
}
}
}
AI Distiller (aid) DOES NOT perform analysis - it generates prompts with distilled code for AI agents to use:
.aid/ directory or stdoutImportant: The output is always a prompt with distilled code - NOT the analysis itself!
aid_hunt_bugs({ target_path: "src/auth/" }).aid/bug-hunting.mdAlternative workflow for large codebases:
Note: AI Distiller only generates prompts - the actual analysis is performed by AI agents!
.aid/ directory as markdown files.aid/ACTION.TIMESTAMP.FOLDER.md.aid/ directory for large analysesAID_ROOT - REQUIRED for user-scoped installation: Root directory for analysis. Without this, the tool cannot determine which project to analyze.⚠️ Critical Information:
--scope=user): Automatically uses the current project directory--scope=user): MUST set AID_ROOT to your project pathFor user-scoped installations, you MUST configure the project path:
{
"mcpServers": {
"aid": {
"command": "npx",
"args": ["-y", "@janreges/ai-distiller-mcp"],
"env": {
"AID_ROOT": "/absolute/path/to/your/project" // REQUIRED!
}
}
}
}
Control what code elements are included:
include_public: true/false - Public members (default: true)include_protected: true/false - Protected members (default: false)include_internal: true/false - Internal/package-private (default: false)include_private: true/false - Private members (default: false)include_implementation: false - Only signatures (smallest output)include_implementation: true - Full method/function bodies (largest output)| Configuration | Output Size | Use Case |
|---|---|---|
| Public only, no implementation | Smallest | API documentation |
| All visibility, no implementation | Medium | Architecture overview |
| Public + implementation | Large | Detailed API analysis |
| All visibility + implementation | Largest | Deep code analysis |
For large projects, aid's output may exceed AI context limits. Strategies:
Target specific directories:
aid_analyze({
target_path: "src/auth/", // Just auth module
ai_action: "prompt-for-bug-hunting"
})
Use file patterns:
aid_analyze({
target_path: "src/",
include_patterns: "*.py", // Python files only
exclude_patterns: "*test*,*mock*"
})
Progressive analysis:
include_implementation: false)Output to files:
.aid/ directory// Example prompts:
// 1. "Use aid to find bugs in my authentication module"
// 2. "Run aid bug hunter on src/api/ focusing on input validation"
// 3. "Check src/services/ for memory leaks with aid, include private methods"
// Claude will call:
aid_hunt_bugs({
target_path: "src/auth/",
focus_area: "memory leaks and race conditions",
include_private: true,
include_implementation: true // Include code bodies
})
// Returns: Bug-hunting PROMPT with distilled code (NOT bug list!)
// Output: .aid/bug-hunting-2024-06-20.auth.md
// Next step: AI agent reads this file and performs the actual bug analysis
// More examples:
aid_hunt_bugs({
target_path: "src/api/",
focus_area: "input validation",
include_private: false // Public API only
})
aid_hunt_bugs({
target_path: "src/components/",
include_patterns: "*.tsx",
focus_area: "React hooks usage"
})
// Example prompts:
// 1. "Use aid to suggest refactoring for src/utils/ to reduce complexity"
// 2. "Run aid refactoring analysis on src/services/ for better testability"
// 3. "Apply aid to modernize legacy code in src/legacy/, show all methods"
// Claude will call:
aid_suggest_refactoring({
target_path: "src/auth/",
refactoring_goal: "improve testability",
include_implementation: false // Signatures only for overview
})
// Returns: Refactoring PROMPT with distilled code (NOT refactoring suggestions!)
// Next step: Claude reads this prompt and generates actual refactoring suggestions
// More examples:
aid_suggest_refactoring({
target_path: "src/components/",
refactoring_goal: "reduce complexity",
include_implementation: true,
include_private: true // Include all methods
})
aid_suggest_refactoring({
target_path: "src/database/",
refactoring_goal: "modernize code patterns",
include_patterns: "*.js",
exclude_patterns: "*test*"
})
// Example prompts:
// 1. "Use aid to generate architecture diagrams for src/"
// 2. "Create data flow diagrams with aid for src/api/ endpoints"
// 3. "Run aid diagram generator on src/services/ showing class relationships"
// Claude will call:
aid_generate_diagram({
target_path: "src/",
diagram_focus: "authentication flow",
include_private: true,
include_implementation: false // Structure only
})
// Returns: Diagram generation PROMPT with distilled code (NOT diagrams!)
// Next step: AI agent reads this and creates actual Mermaid diagrams
// More examples:
aid_generate_diagram({
target_path: "src/api/",
diagram_focus: "API endpoints",
include_private: false, // Public API only
include_protected: true
})
aid_generate_diagram({
target_path: "src/components/",
diagram_focus: "component hierarchy",
include_patterns: "*.tsx,*.jsx"
})
// Example prompts:
// 1. "Use aid security analyzer on src/api/ and save to security-report.md"
// 2. "Run aid OWASP check on src/auth/ with all visibility levels"
// 3. "Execute aid security audit on src/database/ and analyze immediately"
// Claude will call:
aid_analyze_security({
target_path: "src/api/",
security_focus: "input validation and SQL injection",
include_private: true,
include_implementation: true // Need to see actual code
})
// Returns: Security audit PROMPT with distilled code (NOT vulnerabilities!)
// Output: .aid/security-analysis-2024-06-20.api.md
// Next step: AI agent analyzes code following the prompt instructions
// More examples:
aid_analyze_security({
target_path: "src/auth/",
security_focus: "authentication bypass",
include_private: true,
include_protected: true,
include_internal: true // Full visibility
})
aid_analyze_security({
target_path: "src/controllers/",
security_focus: "XSS vulnerabilities",
include_patterns: "*.php",
include_implementation: true
})
// Example prompts:
// 1. "Use aid to generate API docs for src/core/ public methods only"
// 2. "Create developer documentation with aid for src/utils/ including examples"
// 3. "Run aid docs generator on src/lib/ and write to API.md"
// Claude will call:
aid_generate_docs({
target_path: "src/core/",
doc_type: "api-reference",
audience: "external developers",
include_private: false // Public API only
})
// Returns: Documentation generation PROMPT with distilled code (NOT docs!)
// Output: .aid/docs-api-reference-2024-06-20.core.md
// Next step: AI agent generates actual documentation from the prompt
// More examples:
aid_generate_docs({
target_path: "src/components/",
doc_type: "single-file-docs",
audience: "internal team",
include_private: true,
include_protected: true
})
aid_generate_docs({
target_path: "src/services/",
doc_type: "multi-file-docs",
include_patterns: "*.ts",
exclude_patterns: "*.test.ts"
})
// Example prompts:
// 1. "Use aid to analyze src/ with deep file analysis workflow"
// 2. "Run aid performance analysis on src/services/ and execute immediately"
// 3. "Apply aid best practices check to src/utils/ with custom output path"
// For advanced users who need specific AI actions:
aid_analyze({
ai_action: "flow-for-deep-file-to-file-analysis",
target_path: "src/",
user_query: "Focus on authentication and authorization patterns",
include_patterns: "*.py,*.js"
})
// Output: .aid/flow-for-deep-file-to-file-analysis-2024-06-20.src.md
// More examples:
aid_analyze({
ai_action: "prompt-for-performance-analysis",
target_path: "src/api/",
include_implementation: true,
output_format: "md"
})
aid_analyze({
ai_action: "prompt-for-best-practices-analysis",
target_path: "src/components/",
include_private: true,
exclude_patterns: "*test*,*mock*"
})
Available AI actions:
flow-for-deep-file-to-file-analysis - Systematic file-by-file analysis workflowflow-for-multi-file-docs - Multi-file documentation generation workflowprompt-for-refactoring-suggestion - Refactoring analysis promptprompt-for-complex-codebase-analysis - Enterprise-grade analysis promptprompt-for-security-analysis - Security audit promptprompt-for-performance-analysis - Performance optimization promptprompt-for-best-practices-analysis - Best practices evaluation promptprompt-for-bug-hunting - Bug detection promptprompt-for-single-file-docs - Single file documentation promptprompt-for-diagrams - Diagram generation prompt// Example prompts:
// 1. "Use aid to extract structure from src/main.py with all visibility"
// 2. "Show me the API of src/auth/service.ts using aid, public only"
// 3. "Get aid distillation of src/utils.js including implementation"
// Claude will call:
distill_file({
file_path: "src/auth/service.ts",
include_private: false, // Public API only
include_implementation: false // Signatures only
})
// Returns: Distilled code structure directly
// More examples:
distill_file({
file_path: "src/models/user.py",
include_private: true,
include_protected: true,
include_implementation: true, // Full code
output_format: "json"
})
distill_file({
file_path: "src/components/Button.tsx",
include_comments: true,
output_format: "md"
})
// Example prompts:
// 1. "Use aid to distill entire src/services/ directory"
// 2. "Extract structure from src/api/ with aid, exclude tests"
// 3. "Run aid on src/components/ showing protected members"
// Claude will call:
distill_directory({
directory_path: "src/services/",
include_private: false,
include_implementation: false,
recursive: true
})
// Returns: Distilled structure for all files
// More examples:
distill_directory({
directory_path: "src/api/",
include_patterns: "*.ts,*.js",
exclude_patterns: "*test*,*spec*",
include_protected: true,
include_internal: true
})
distill_directory({
directory_path: "src/components/",
include_patterns: "*.tsx",
include_private: true,
include_implementation: true,
output_format: "jsonl" // One JSON per file
})
User: "Use aid to check src/ for potential bugs"
1. Claude calls aid_hunt_bugs(target_path="src/", include_private=true)
2. aid generates bug-hunting PROMPT + distilled code → .aid/bug-hunting-*.md
3. Claude reads the generated prompt file
4. Claude executes the prompt instructions to find actual bugs
5. Claude provides bug findings and fixes
User: "Run aid security audit on src/api/ endpoints and analyze"
1. Claude uses aid_analyze_security(target_path="src/api/", include_implementation=true)
2. Reads .aid/security-analysis-*.md file
3. Reviews OWASP-categorized findings
4. Suggests security improvements
User: "Help me understand src/ architecture using aid diagrams"
1. Claude uses aid_generate_diagram(target_path="src/")
2. Reads .aid/diagrams-*.md file
3. Presents 10 different architectural views
4. Explains key components and relationships
User: "Apply aid refactoring analysis to src/services/ for complexity"
1. Claude uses aid_suggest_refactoring(target_path="src/services/", refactoring_goal="reduce complexity")
2. Reads .aid/refactoring-suggestion-*.md file
3. Provides specific refactoring suggestions
4. Shows before/after code examples
Python, TypeScript, JavaScript, Go, Java, C#, Rust, Ruby, Swift, Kotlin, PHP, C++, C
If you encounter issues:
aid is in your PATH or build directory*.go,*.pyMIT License - see LICENSE file
AI Distiller (aid) - https://github.com/janreges/ai-distiller
Authored by Claude Code & Ján Regeš from SiteOne (Czech Republic)
Explore the project on GitHub
FAQs
AI Distiller (aid) - Essential code structure extractor for LLMs. Provides AI with accurate code signatures, data types, and API contracts from your actual codebase, reducing guesswork and trial-error coding. Accelerates analysis workflows including secur
We found that @janreges/ai-distiller-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Socket Threat Research maps a rare inside look at OtterCookie’s npm-Vercel-GitHub chain, adding 197 malicious packages and evidence of North Korean operators.
Research
Socket researchers identified a malicious Chrome extension that manipulates Raydium swaps to inject an undisclosed SOL transfer, quietly routing fees to an attacker wallet.
Research
/Security News
Another wave of Shai-Hulud campaign has hit npm with more than 500 packages and 700+ versions affected.