{"id":9844,"library":"jcodemunch-mcp","title":"jcodemunch-mcp: Token-Efficient Code Exploration Server","description":"jcodemunch-mcp is a Python library providing a token-efficient MCP (Multi-language Code Processing) server for deep source code exploration. It leverages tree-sitter for AST parsing across 70+ languages, offering tools like cross-language AST pattern matching, symbol provenance, project intelligence, and tectonic analysis. The current version is 1.52.0, with a rapid release cadence focusing on new analysis capabilities and performance improvements.","status":"active","version":"1.52.0","language":"en","source_language":"en","source_url":"https://github.com/jgravelle/jcodemunch-mcp","tags":["code analysis","AST","tree-sitter","LLM","AI","refactoring","security","developer tools"],"install":[{"cmd":"pip install jcodemunch-mcp","lang":"bash","label":"Install jcodemunch-mcp"}],"dependencies":[],"imports":[{"note":"The main client class is explicitly named `MCPClient` for consistency with the library's 'MCP server' functionality.","wrong":"from jcodemunch_mcp import Client","symbol":"MCPClient","correct":"from jcodemunch_mcp import MCPClient"}],"quickstart":{"code":"import os\nfrom jcodemunch_mcp import MCPClient\n\n# Initialize the client. This assumes a local server or embedded functionality.\n# For advanced setups, authentication or server URL might be configured via env vars or constructor args.\nclient = MCPClient()\n\n# Define the repository path to analyze (e.g., the current directory).\n# For real-world use, replace with your target repository path.\nrepo_path = os.getcwd()\n\nprint(f\"Indexing repository at '{repo_path}' for analysis...\")\n# It's good practice to explicitly index the folder first.\n# Note: This might take time for large repositories.\nclient.index_folder(repo_path=repo_path)\nprint(\"Indexing complete.\")\n\n# Example 1: Search for a common anti-pattern (e.g., 'empty_catch') using cross-language AST matching.\nprint(f\"\\nSearching for 'empty_catch' anti-pattern...\")\nresults_ast = client.search_ast(repo_path=repo_path, query='empty_catch')\n\nif results_ast:\n    print(f\"Found {len(results_ast)} 'empty_catch' instances. Showing first 3:\")\n    for r in results_ast[:3]:\n        print(f\"- {r['file']}:{r['line']} (Lang: {r['lang']}):\\n  ```\\n{r['snippet']}\\n  ```\")\nelse:\n    print(\"No 'empty_catch' instances found.\")\n\n# Example 2: Get project intelligence (e.g., Dockerfiles, CI/CD configs).\nprint(f\"\\nGetting project intelligence for '{repo_path}'...\")\nproject_intel = client.get_project_intel(repo_path=repo_path)\n\nif project_intel and 'dockerfiles' in project_intel:\n    print(f\"Found {len(project_intel['dockerfiles'])} Dockerfiles.\")\n    for df in project_intel['dockerfiles'][:1]: # Show details for the first Dockerfile\n        print(f\"- Dockerfile at: {df['path']}\")\n        print(f\"  Entrypoint: {df.get('entrypoint', 'N/A')}\")\n        print(f\"  Stages: {', '.join([s['name'] for s in df.get('stages', [])])}\")\nelse:\n    print(\"No Dockerfiles or significant project intelligence found.\")","lang":"python","description":"This quickstart initializes the `MCPClient`, indexes the current working directory, then demonstrates two core functionalities: cross-language AST pattern matching for 'empty_catch' anti-patterns and retrieving project intelligence, such as discovered Dockerfiles."},"warnings":[{"fix":"Ensure `repo_path` has at least 2 components (e.g., `/app/src`) when running in Docker, Podman, or devcontainers. Bare `/` is still rejected. Alternatively, use the `trusted_folders` parameter for manual override.","message":"Path depth requirements for `index_folder` in container environments changed.","severity":"gotcha","affected_versions":">=1.50.1"},{"fix":"Be aware that the client now maintains per-branch delta layers instead of re-indexing full repositories on branch switches. This optimizes storage and performance but can lead to unexpected behavior if manual full re-indexing (e.g., after a hard reset) is expected. Tools auto-detect the current branch.","message":"Branch-Aware Delta Indexing introduced, changing indexing behavior and resource usage.","severity":"gotcha","affected_versions":">=1.50.0"},{"fix":"`search_ast` supports cross-language pattern matching. Avoid using language-specific tree-sitter node types directly. Instead, leverage the provided preset anti-pattern detectors (e.g., 'empty_catch', 'bare_except') or focus on abstract semantic patterns for universal matches.","message":"Misusing `search_ast` queries with language-specific AST node types.","severity":"gotcha","affected_versions":">=1.52.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"The primary client class is `MCPClient`. Use `from jcodemunch_mcp import MCPClient`.","cause":"Attempting to import the main client class using an incorrect name, `Client`.","error":"ImportError: cannot import name 'Client' from 'jcodemunch_mcp'"},{"fix":"Provide a more specific path (e.g., `/app/my-repo`) to `client.index_folder()`, or use the `trusted_folders` parameter in the `MCPClient` constructor or `index_folder` method to explicitly allow shallow paths (e.g., `client = MCPClient(trusted_folders=['/usr/src'])`).","cause":"Attempting to index a repository path with insufficient depth (e.g., '/app' or '/usr/src') when running inside a container, which is restricted by design to prevent accidental indexing of system roots.","error":"ValueError: Path '/usr/src' too shallow for indexing. Minimum 2 components required in container environments."},{"fix":"For very large repositories, try indexing smaller sub-sections if possible. If running in a container, increase the allocated memory for the container. The library is optimized for token efficiency, but initial AST parsing can still be memory-intensive. Consider filtering paths with a `.codemunchignore` file or using `trusted_folders` to limit the indexing scope.","cause":"Indexing a very large or highly complex repository (e.g., monorepo with thousands of files) consumed too much memory or hit an internal limit, especially in resource-constrained environments.","error":"jcodemunch_mcp.exceptions.IndexingError: Maximum memory limit exceeded during repository indexing. Consider reducing scope or increasing resources."}]}