| Name | ctags-mcp JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | MCP server for ctags-based code navigation in Claude Code |
| upload_time | 2025-09-18 16:14:56 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) 2024 Generated with Claude Code Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
ai
claude
code-navigation
ctags
mcp
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MCP Ctags Server
[](https://www.python.org/downloads/)
[](LICENSE)
A Model Context Protocol (MCP) server that transforms ctags from a command-line utility into a native code navigation system for Claude Code. Built with a functional programming approach and comprehensive type safety.
## Quick Start
```bash
# Install the package
pip install ctags-mcp
# Generate tags for your project
ctags -R .
# Add to Claude Desktop config
{
"mcpServers": {
"ctags": {
"command": "ctags-mcp"
}
}
}
# Optional: Auto-regenerate tags when code changes
# Copy .claude/settings.json to your project root
```
**[📖 Full Installation Guide](INSTALL.md)** | **[🔄 Auto-Regeneration Setup](AUTO_REGENERATION.md)**
## ✨ Features
- **🚀 20x Performance**: Index-based symbol lookup vs reading entire files
- **🔍 Smart Search**: Regex patterns, type filtering, scope-aware queries
- **📁 Universal Support**: Works with any ctags-supported language
- **🎯 Precise Context**: Get source code around symbols with configurable line counts
- **🔧 Auto-Detection**: Finds tags files in current and parent directories
- **⚡ Zero Configuration**: Works out of the box with standard ctags files
## 🎯 What It Does
Transform code exploration from this:
```bash
# Traditional approach - slow, imprecise
find . -name "*.py" | xargs grep "async def"
grep -r "class.*Service" src/
```
To this:
```text
# Natural language with Claude
"Find all async functions in this project"
"Show me service classes with their locations"
"Get the AsyncBatchProcessor definition with context"
```
## 📊 Performance Comparison
| Task | Traditional | MCP Ctags | Improvement |
|------|-------------|-----------|-------------|
| Find symbols | ~530ms | ~7ms | **79x faster** |
| Files read | 53+ files | 0 files | **∞x better** |
| Query accuracy | Manual parsing | Structured data | **More reliable** |
| Scalability | Linear O(n) | Constant O(1) | **Scales infinitely** |
## 🛠️ MCP Tools Available
### `ctags_detect`
Auto-detects and validates ctags file in working directory.
### `ctags_find_symbol`
Finds symbols by name or regex pattern with comprehensive filtering.
### `ctags_list_symbols`
Lists all symbols of a specific type (functions, classes, methods, variables).
### `ctags_get_location`
Gets source code context around a specific symbol.
### `ctags_search_in_files`
Searches across multiple file patterns simultaneously.
## 🎯 Usage Examples
Once configured with Claude Desktop:
- **"Find all async functions"** → Instantly locates async functions across the codebase
- **"Show me the AsyncBatchProcessor class"** → Gets class definition with source context
- **"List service classes in this project"** → Finds all classes with "Service" in the name
- **"Find authentication-related symbols"** → Pattern-matches auth symbols across all types
## 📁 Project Structure
```
ctags-mcp/
├── src/ctags_mcp/ # Main package
│ ├── ctags_parser.py # Functional ctags file parsing
│ ├── symbol_search.py # Search and filtering functions
│ ├── ctags_server.py # FastMCP server with tool definitions
│ └── main.py # CLI entry point
├── src/tests/ # Comprehensive test suite
├── pyproject.toml # Package configuration
├── LICENSE # MIT License
├── README.md # This file
└── INSTALL.md # Installation guide
```
## 🧪 Testing
The implementation includes comprehensive testing:
```bash
# Run all tests
pytest
# With coverage
pytest --cov=src/ctags_mcp
# Results: 31 tests passing, covering all functionality
```
## 🏗️ Architecture
Built with functional programming principles:
- **Pure functions** for parsing and searching
- **Pydantic models** for type safety
- **Zero classes** except for data models
- **Comprehensive error handling** for malformed files
- **Performance optimized** for large codebases
## 🔧 Development
```bash
# Clone and setup
git clone <repository-url>
cd ctags-mcp
pip install -e ".[dev]"
# Code quality
black src/ # Format code
ruff check src/ # Lint code
mypy src/ # Type check
pytest # Run tests
```
## 📈 Performance Insights
Real-world testing with 1,050 symbols:
```
📁 Tags File Information:
Format: exuberant
Total entries: 1050
Functions: 304, Classes: 89, Methods: 512, Variables: 145
🔍 Search Examples:
• Async functions: 4 found in ~7ms
• Service classes: 15 found in ~7ms
• Auth symbols: 23 found in ~7ms
• CLI symbols: 129 found in ~7ms
🚀 Efficiency: 79x faster than traditional file scanning
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make changes with tests: `pytest`
4. Submit a pull request
## 📜 License
MIT License - see [LICENSE](LICENSE) for details.
## 🙏 Acknowledgments
- Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk) from Anthropic
- Uses [Universal Ctags](https://ctags.io/) for symbol indexing
- Inspired by the need for efficient code navigation in Claude Code
---
**Transform your code navigation today!** Install ctags-mcp and experience the power of index-based code exploration with Claude.
Raw data
{
"_id": null,
"home_page": null,
"name": "ctags-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, claude, code-navigation, ctags, mcp",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0f/81/a966e5c5919048e9a25e8013a4633b6bc25888016ce7fbe2503ca6699634/ctags_mcp-1.0.0.tar.gz",
"platform": null,
"description": "# MCP Ctags Server\n\n[](https://www.python.org/downloads/)\n[](LICENSE)\n\nA Model Context Protocol (MCP) server that transforms ctags from a command-line utility into a native code navigation system for Claude Code. Built with a functional programming approach and comprehensive type safety.\n\n## Quick Start\n\n```bash\n# Install the package\npip install ctags-mcp\n\n# Generate tags for your project\nctags -R .\n\n# Add to Claude Desktop config\n{\n \"mcpServers\": {\n \"ctags\": {\n \"command\": \"ctags-mcp\"\n }\n }\n}\n\n# Optional: Auto-regenerate tags when code changes\n# Copy .claude/settings.json to your project root\n```\n\n**[\ud83d\udcd6 Full Installation Guide](INSTALL.md)** | **[\ud83d\udd04 Auto-Regeneration Setup](AUTO_REGENERATION.md)**\n\n## \u2728 Features\n\n- **\ud83d\ude80 20x Performance**: Index-based symbol lookup vs reading entire files\n- **\ud83d\udd0d Smart Search**: Regex patterns, type filtering, scope-aware queries\n- **\ud83d\udcc1 Universal Support**: Works with any ctags-supported language\n- **\ud83c\udfaf Precise Context**: Get source code around symbols with configurable line counts\n- **\ud83d\udd27 Auto-Detection**: Finds tags files in current and parent directories\n- **\u26a1 Zero Configuration**: Works out of the box with standard ctags files\n\n## \ud83c\udfaf What It Does\n\nTransform code exploration from this:\n```bash\n# Traditional approach - slow, imprecise\nfind . -name \"*.py\" | xargs grep \"async def\"\ngrep -r \"class.*Service\" src/\n```\n\nTo this:\n```text\n# Natural language with Claude\n\"Find all async functions in this project\"\n\"Show me service classes with their locations\"\n\"Get the AsyncBatchProcessor definition with context\"\n```\n\n## \ud83d\udcca Performance Comparison\n\n| Task | Traditional | MCP Ctags | Improvement |\n|------|-------------|-----------|-------------|\n| Find symbols | ~530ms | ~7ms | **79x faster** |\n| Files read | 53+ files | 0 files | **\u221ex better** |\n| Query accuracy | Manual parsing | Structured data | **More reliable** |\n| Scalability | Linear O(n) | Constant O(1) | **Scales infinitely** |\n\n## \ud83d\udee0\ufe0f MCP Tools Available\n\n### `ctags_detect`\nAuto-detects and validates ctags file in working directory.\n\n### `ctags_find_symbol`\nFinds symbols by name or regex pattern with comprehensive filtering.\n\n### `ctags_list_symbols`\nLists all symbols of a specific type (functions, classes, methods, variables).\n\n### `ctags_get_location`\nGets source code context around a specific symbol.\n\n### `ctags_search_in_files`\nSearches across multiple file patterns simultaneously.\n\n## \ud83c\udfaf Usage Examples\n\nOnce configured with Claude Desktop:\n\n- **\"Find all async functions\"** \u2192 Instantly locates async functions across the codebase\n- **\"Show me the AsyncBatchProcessor class\"** \u2192 Gets class definition with source context\n- **\"List service classes in this project\"** \u2192 Finds all classes with \"Service\" in the name\n- **\"Find authentication-related symbols\"** \u2192 Pattern-matches auth symbols across all types\n\n## \ud83d\udcc1 Project Structure\n\n```\nctags-mcp/\n\u251c\u2500\u2500 src/ctags_mcp/ # Main package\n\u2502 \u251c\u2500\u2500 ctags_parser.py # Functional ctags file parsing\n\u2502 \u251c\u2500\u2500 symbol_search.py # Search and filtering functions\n\u2502 \u251c\u2500\u2500 ctags_server.py # FastMCP server with tool definitions\n\u2502 \u2514\u2500\u2500 main.py # CLI entry point\n\u251c\u2500\u2500 src/tests/ # Comprehensive test suite\n\u251c\u2500\u2500 pyproject.toml # Package configuration\n\u251c\u2500\u2500 LICENSE # MIT License\n\u251c\u2500\u2500 README.md # This file\n\u2514\u2500\u2500 INSTALL.md # Installation guide\n```\n\n## \ud83e\uddea Testing\n\nThe implementation includes comprehensive testing:\n\n```bash\n# Run all tests\npytest\n\n# With coverage\npytest --cov=src/ctags_mcp\n\n# Results: 31 tests passing, covering all functionality\n```\n\n## \ud83c\udfd7\ufe0f Architecture\n\nBuilt with functional programming principles:\n\n- **Pure functions** for parsing and searching\n- **Pydantic models** for type safety\n- **Zero classes** except for data models\n- **Comprehensive error handling** for malformed files\n- **Performance optimized** for large codebases\n\n## \ud83d\udd27 Development\n\n```bash\n# Clone and setup\ngit clone <repository-url>\ncd ctags-mcp\npip install -e \".[dev]\"\n\n# Code quality\nblack src/ # Format code\nruff check src/ # Lint code\nmypy src/ # Type check\npytest # Run tests\n```\n\n## \ud83d\udcc8 Performance Insights\n\nReal-world testing with 1,050 symbols:\n\n```\n\ud83d\udcc1 Tags File Information:\n Format: exuberant\n Total entries: 1050\n Functions: 304, Classes: 89, Methods: 512, Variables: 145\n\n\ud83d\udd0d Search Examples:\n \u2022 Async functions: 4 found in ~7ms\n \u2022 Service classes: 15 found in ~7ms\n \u2022 Auth symbols: 23 found in ~7ms\n \u2022 CLI symbols: 129 found in ~7ms\n\n\ud83d\ude80 Efficiency: 79x faster than traditional file scanning\n```\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make changes with tests: `pytest`\n4. Submit a pull request\n\n## \ud83d\udcdc License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk) from Anthropic\n- Uses [Universal Ctags](https://ctags.io/) for symbol indexing\n- Inspired by the need for efficient code navigation in Claude Code\n\n---\n\n**Transform your code navigation today!** Install ctags-mcp and experience the power of index-based code exploration with Claude.",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Generated with Claude Code Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "MCP server for ctags-based code navigation in Claude Code",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/gladiatr72/mcp-ctags",
"Issues": "https://github.com/gladiatr72/mcp-ctags/issues",
"Repository": "https://github.com/gladiatr72/mcp-ctags"
},
"split_keywords": [
"ai",
" claude",
" code-navigation",
" ctags",
" mcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e940a12694d225621f9a07ca8730211a260d49aeafd3ee1bd31aa87b80cc0992",
"md5": "26a638081aafa5b6cc87cd4031d34d4c",
"sha256": "6d71592a191355bf20fefd6a55231c95f08ea2f532a1db7614184294ce5db61c"
},
"downloads": -1,
"filename": "ctags_mcp-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "26a638081aafa5b6cc87cd4031d34d4c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14041,
"upload_time": "2025-09-18T16:14:55",
"upload_time_iso_8601": "2025-09-18T16:14:55.485352Z",
"url": "https://files.pythonhosted.org/packages/e9/40/a12694d225621f9a07ca8730211a260d49aeafd3ee1bd31aa87b80cc0992/ctags_mcp-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0f81a966e5c5919048e9a25e8013a4633b6bc25888016ce7fbe2503ca6699634",
"md5": "298f33d1353a81f1c7125554fdf6279d",
"sha256": "f1a421ead36531f2766a5e3a840fbf0656cc3b574fc84bd62e6a0b1044c873a1"
},
"downloads": -1,
"filename": "ctags_mcp-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "298f33d1353a81f1c7125554fdf6279d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 27419,
"upload_time": "2025-09-18T16:14:56",
"upload_time_iso_8601": "2025-09-18T16:14:56.391921Z",
"url": "https://files.pythonhosted.org/packages/0f/81/a966e5c5919048e9a25e8013a4633b6bc25888016ce7fbe2503ca6699634/ctags_mcp-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-18 16:14:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gladiatr72",
"github_project": "mcp-ctags",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ctags-mcp"
}
