mcp-code-indexer 1.2.3__tar.gz → 1.4.0__tar.gz

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 (42) hide show
  1. {mcp_code_indexer-1.2.3/src/mcp_code_indexer.egg-info → mcp_code_indexer-1.4.0}/PKG-INFO +160 -38
  2. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/README.md +157 -37
  3. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/docs/api-reference.md +35 -24
  4. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/docs/architecture.md +9 -7
  5. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/docs/configuration.md +24 -18
  6. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/docs/contributing.md +9 -3
  7. mcp_code_indexer-1.4.0/docs/git-hook-setup.md +243 -0
  8. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/migrations/003_project_overviews.sql +3 -3
  9. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/pyproject.toml +4 -2
  10. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/requirements.txt +4 -2
  11. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/setup.py +6 -4
  12. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/__init__.py +1 -1
  13. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/database/database.py +118 -7
  14. mcp_code_indexer-1.4.0/src/mcp_code_indexer/git_hook_handler.py +542 -0
  15. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/logging_config.py +76 -8
  16. mcp_code_indexer-1.4.0/src/mcp_code_indexer/main.py +855 -0
  17. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/server/mcp_server.py +12 -3
  18. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0/src/mcp_code_indexer.egg-info}/PKG-INFO +160 -38
  19. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer.egg-info/SOURCES.txt +2 -0
  20. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer.egg-info/requires.txt +2 -0
  21. mcp_code_indexer-1.2.3/src/mcp_code_indexer/main.py +0 -399
  22. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/LICENSE +0 -0
  23. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/MANIFEST.in +0 -0
  24. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/migrations/001_initial.sql +0 -0
  25. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/migrations/002_performance_indexes.sql +0 -0
  26. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/setup.cfg +0 -0
  27. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/__main__.py +0 -0
  28. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/data/stop_words_english.txt +0 -0
  29. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/database/__init__.py +0 -0
  30. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/database/models.py +0 -0
  31. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/error_handler.py +0 -0
  32. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/file_scanner.py +0 -0
  33. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/merge_handler.py +0 -0
  34. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/middleware/__init__.py +0 -0
  35. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/middleware/error_middleware.py +0 -0
  36. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/server/__init__.py +0 -0
  37. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/tiktoken_cache/9b5ad71b2ce5302211f9c61530b329a4922fc6a4 +0 -0
  38. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/token_counter.py +0 -0
  39. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer/tools/__init__.py +0 -0
  40. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer.egg-info/dependency_links.txt +0 -0
  41. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer.egg-info/entry_points.txt +0 -0
  42. {mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/src/mcp_code_indexer.egg-info/top_level.txt +0 -0
{mcp_code_indexer-1.2.3/src/mcp_code_indexer.egg-info → mcp_code_indexer-1.4.0}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: mcp-code-indexer
3
- Version: 1.2.3
3
+ Version: 1.4.0
4
4
  Summary: MCP server that tracks file descriptions across codebases, enabling AI agents to efficiently navigate and understand code through searchable summaries and token-aware overviews.
5
5
  Author: MCP Code Indexer Contributors
6
6
  Maintainer: MCP Code Indexer Contributors
@@ -35,6 +35,8 @@ Requires-Dist: gitignore_parser==0.1.11
35
35
  Requires-Dist: pydantic>=2.8.0
36
36
  Requires-Dist: aiofiles==23.2.0
37
37
  Requires-Dist: aiosqlite==0.19.0
38
+ Requires-Dist: aiohttp>=3.8.0
39
+ Requires-Dist: tenacity>=8.0.0
38
40
  Provides-Extra: dev
39
41
  Requires-Dist: pytest>=8.0.0; extra == "dev"
40
42
  Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -55,11 +57,11 @@ Dynamic: requires-python
55
57
 
56
58
  # MCP Code Indexer 🚀
57
59
 
58
- [![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?1)](https://badge.fury.io/py/mcp-code-indexer)
59
- [![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?1)](https://pypi.org/project/mcp-code-indexer/)
60
+ [![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?2)](https://badge.fury.io/py/mcp-code-indexer)
61
+ [![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?2)](https://pypi.org/project/mcp-code-indexer/)
60
62
  [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
61
63
 
62
- A production-ready **Model Context Protocol (MCP) server** that provides intelligent codebase navigation for AI agents through searchable file descriptions, token-aware overviews, and advanced merge capabilities.
64
+ A production-ready **Model Context Protocol (MCP) server** that revolutionizes how AI agents navigate and understand codebases. Instead of repeatedly scanning files, agents get instant access to intelligent descriptions, semantic search, and context-aware recommendations.
63
65
 
64
66
  ## 🎯 What It Does
65
67
 
@@ -75,40 +77,107 @@ Perfect for AI-powered code review, refactoring tools, documentation generation,
75
77
 
76
78
  ## ⚡ Quick Start
77
79
 
78
- ### Install from PyPI
80
+ ### 👨‍💻 For Developers
81
+
82
+ Get started integrating MCP Code Indexer into your AI agent workflow:
79
83
 
80
84
  ```bash
81
85
  # Install the package
82
86
  pip install mcp-code-indexer
83
87
 
84
- # Run the server
85
- mcp-code-indexer --token-limit 32000
88
+ # Start the MCP server
89
+ mcp-code-indexer
90
+
91
+ # Connect your MCP client and start using tools
92
+ # See API Reference for complete tool documentation
93
+ ```
94
+
95
+ ### 🔧 For System Administrators
86
96
 
87
- # Check version
97
+ Deploy and configure the server for your team:
98
+
99
+ ```bash
100
+ # Production deployment with custom settings
101
+ mcp-code-indexer \
102
+ --token-limit 64000 \
103
+ --db-path /data/mcp-index.db \
104
+ --cache-dir /var/cache/mcp \
105
+ --log-level INFO
106
+
107
+ # Check installation
88
108
  mcp-code-indexer --version
89
109
  ```
90
110
 
91
- ### Install from Source
111
+ ### 🎯 For Everyone
112
+
113
+ **New to MCP Code Indexer?** Start here:
114
+
115
+ 1. **Install**: `pip install mcp-code-indexer`
116
+ 2. **Run**: `mcp-code-indexer --token-limit 32000`
117
+ 3. **Connect**: Use your favorite MCP client
118
+ 4. **Explore**: Try the `check_codebase_size` tool first
119
+
120
+ **Development Setup**:
92
121
 
93
122
  ```bash
94
- # Clone and setup
95
- git clone https://github.com/your-username/mcp-code-indexer.git
123
+ # Clone and setup for contributing
124
+ git clone https://github.com/fluffypony/mcp-code-indexer.git
96
125
  cd mcp-code-indexer
97
126
 
98
- # Install in development mode
127
+ # Install in development mode (required)
99
128
  pip install -e .
100
129
 
101
130
  # Run the server
102
131
  mcp-code-indexer --token-limit 32000
103
132
  ```
104
133
 
134
+ ## 🔗 Git Hook Integration
135
+
136
+ 🚀 **NEW Feature**: Automated code indexing with AI-powered analysis! Keep your file descriptions synchronized automatically as your codebase evolves.
137
+
138
+ ### 👤 For Users: Quick Setup
139
+
140
+ ```bash
141
+ # Set your OpenRouter API key
142
+ export OPENROUTER_API_KEY="sk-or-v1-your-api-key-here"
143
+
144
+ # Test git hook functionality
145
+ mcp-code-indexer --githook
146
+
147
+ # Install post-commit hook
148
+ cp examples/git-hooks/post-commit .git/hooks/
149
+ chmod +x .git/hooks/post-commit
150
+ ```
151
+
152
+ ### 👨‍💻 For Developers: How It Works
153
+
154
+ The git hook integration provides intelligent automation:
155
+
156
+ - **📊 Git Analysis**: Automatically analyzes git diffs after commits/merges
157
+ - **🤖 AI Processing**: Uses OpenRouter API with Anthropic's Claude Sonnet 4
158
+ - **⚡ Smart Updates**: Only processes files that actually changed
159
+ - **🔄 Overview Maintenance**: Updates project overview when structure changes
160
+ - **🛡️ Error Isolation**: Git operations continue even if indexing fails
161
+ - **⏱️ Rate Limiting**: Built-in retry logic with exponential backoff
162
+
163
+ ### 🎯 Key Benefits
164
+
165
+ 💡 **Zero Manual Work**: Descriptions stay current without any effort
166
+ ⚡ **Performance**: Only analyzes changed files, not entire codebase
167
+ 🔒 **Reliability**: Robust error handling ensures git operations never fail
168
+ 🎛️ **Configurable**: Support for custom models and timeout settings
169
+
170
+ **Learn More**: See [Git Hook Setup Guide](docs/git-hook-setup.md) for complete configuration options and troubleshooting.
171
+
105
172
  ## 🔧 Development Setup
106
173
 
107
- For development work, you **must** install the package in editable mode to ensure proper import resolution:
174
+ ### 👨‍💻 For Contributors
175
+
176
+ Contributing to MCP Code Indexer? Follow these steps for a proper development environment:
108
177
 
109
178
  ```bash
110
179
  # Setup development environment
111
- git clone https://github.com/your-username/mcp-code-indexer.git
180
+ git clone https://github.com/fluffypony/mcp-code-indexer.git
112
181
  cd mcp-code-indexer
113
182
 
114
183
  # Create and activate virtual environment
@@ -126,11 +195,9 @@ python main.py --help
126
195
  mcp-code-indexer --version
127
196
  ```
128
197
 
129
- ### Why Editable Install is Required
130
-
131
- The project uses a proper PyPI package structure with absolute imports like `from mcp_code_indexer.database.database import DatabaseManager`. Without the editable installation (`pip install -e .`), Python cannot resolve these imports and you'll get `ModuleNotFoundError` exceptions.
198
+ ⚠️ **Important**: The editable install (`pip install -e .`) is **required** for development. The project uses proper PyPI package structure with absolute imports like `from mcp_code_indexer.database.database import DatabaseManager`. Without editable installation, you'll get `ModuleNotFoundError` exceptions.
132
199
 
133
- ### Development Workflow
200
+ ### 🎯 Development Workflow
134
201
 
135
202
  ```bash
136
203
  # Activate virtual environment
@@ -158,27 +225,27 @@ mypy src/
158
225
 
159
226
  ## 🛠️ MCP Tools Available
160
227
 
161
- The server provides **11 powerful MCP tools** for intelligent codebase management:
228
+ The server provides **11 powerful MCP tools** for intelligent codebase management. Whether you're an AI agent or human developer, these tools make navigating code effortless.
162
229
 
163
- ### Core Operations
164
- - **`get_file_description`** - Retrieve stored file descriptions instantly
165
- - **`update_file_description`** - Store detailed file summaries and metadata
166
- - **`check_codebase_size`** - Get token count and size-based recommendations with automatic file cleanup
230
+ ### 🎯 For Everyone: Start Here
231
+ - **`check_codebase_size`** - Get instant recommendations for how to navigate your codebase
232
+ - **`search_descriptions`** - Find files by what they do, not just their names
233
+ - **`get_codebase_overview`** - Get a high-level understanding of any project
167
234
 
168
- ### Batch Operations
235
+ ### 👨‍💻 For Developers: Core Operations
236
+ - **`get_file_description`** - Retrieve stored file descriptions instantly
237
+ - **`update_file_description`** - Store detailed file summaries and metadata
169
238
  - **`find_missing_descriptions`** - Scan projects for files without descriptions
170
239
  - **`update_missing_descriptions`** - Bulk update multiple file descriptions
171
240
 
172
- ### Search & Discovery
173
- - **`search_descriptions`** - Fast full-text search across all descriptions
241
+ ### 🔍 For Advanced Users: Search & Discovery
174
242
  - **`get_all_descriptions`** - Complete hierarchical project structure
175
- - **`get_codebase_overview`** - Condensed narrative overview of entire codebase
176
243
  - **`get_word_frequency`** - Technical vocabulary analysis with stop-word filtering
177
-
178
- ### Advanced Features
179
244
  - **`merge_branch_descriptions`** - Two-phase merge with conflict resolution
180
245
  - **`update_codebase_overview`** - Create comprehensive codebase documentation
181
246
 
247
+ 💡 **Pro Tip**: Always start with `check_codebase_size` to get personalized recommendations for navigating your specific codebase.
248
+
182
249
  ## 🏗️ Architecture Highlights
183
250
 
184
251
  ### Performance Optimized
@@ -202,10 +269,16 @@ The server provides **11 powerful MCP tools** for intelligent codebase managemen
202
269
 
203
270
  ## 📖 Documentation
204
271
 
205
- - **[API Reference](docs/api-reference.md)** - Complete MCP tool documentation
206
- - **[Configuration Guide](docs/configuration.md)** - Setup and tuning options
207
- - **[Architecture Overview](docs/architecture.md)** - Technical deep dive
208
- - **[Contributing Guide](docs/contributing.md)** - Development workflow
272
+ ### 👤 For Users
273
+ - **[Git Hook Setup Guide](docs/git-hook-setup.md)** - Automated code indexing setup
274
+ - **[Configuration Guide](docs/configuration.md)** - Production deployment and tuning
275
+
276
+ ### 👨‍💻 For Developers
277
+ - **[API Reference](docs/api-reference.md)** - Complete MCP tool documentation with examples
278
+ - **[Architecture Overview](docs/architecture.md)** - Technical deep dive into system design
279
+
280
+ ### 🤝 For Contributors
281
+ - **[Contributing Guide](docs/contributing.md)** - Development setup and workflow guidelines
209
282
 
210
283
  ## 🚦 System Requirements
211
284
 
@@ -329,6 +402,39 @@ The server provides structured JSON logs for monitoring:
329
402
  }
330
403
  ```
331
404
 
405
+ ## 📋 Command Line Options
406
+
407
+ ### Server Mode (Default)
408
+ ```bash
409
+ mcp-code-indexer [OPTIONS]
410
+
411
+ Options:
412
+ --token-limit INT Maximum tokens before recommending search (default: 32000)
413
+ --db-path PATH SQLite database path (default: ~/.mcp-code-index/tracker.db)
414
+ --cache-dir PATH Cache directory path (default: ~/.mcp-code-index/cache)
415
+ --log-level LEVEL Logging level: DEBUG|INFO|WARNING|ERROR|CRITICAL (default: INFO)
416
+ ```
417
+
418
+ ### Git Hook Mode
419
+ ```bash
420
+ mcp-code-indexer --githook [OPTIONS]
421
+
422
+ # Automated analysis of git changes using OpenRouter API
423
+ # Requires: OPENROUTER_API_KEY environment variable
424
+ ```
425
+
426
+ ### Utility Commands
427
+ ```bash
428
+ # List all projects and branches
429
+ mcp-code-indexer --getprojects
430
+
431
+ # Execute MCP tool directly
432
+ mcp-code-indexer --runcommand '{"method": "tools/call", "params": {...}}'
433
+
434
+ # Export descriptions for a project
435
+ mcp-code-indexer --dumpdescriptions PROJECT_ID [BRANCH]
436
+ ```
437
+
332
438
  ## 🛡️ Security Features
333
439
 
334
440
  - **Input validation** on all MCP tool parameters
@@ -339,10 +445,20 @@ The server provides structured JSON logs for monitoring:
339
445
 
340
446
  ## 🚀 Next Steps
341
447
 
342
- 1. **[Read the API docs](docs/api-reference.md)** to understand available tools
343
- 2. **[Check the configuration guide](docs/configuration.md)** for advanced setup
344
- 3. **[Review the architecture](docs/architecture.md)** for technical details
345
- 4. **[Contribute](docs/contributing.md)** to help improve the project
448
+ Ready to supercharge your AI agents with intelligent codebase navigation?
449
+
450
+ ### 👤 Getting Started
451
+ 1. **[Install and run your first server](#-quick-start)** - Get up and running in 2 minutes
452
+ 2. **[Set up git hooks](docs/git-hook-setup.md)** - Automate your workflow
453
+ 3. **[Configure for production](docs/configuration.md)** - Deploy for your team
454
+
455
+ ### 👨‍💻 For Developers
456
+ 4. **[Explore the API tools](docs/api-reference.md)** - Master all 11 MCP tools
457
+ 5. **[Understand the architecture](docs/architecture.md)** - Deep dive into the technical design
458
+
459
+ ### 🤝 Join the Community
460
+ 6. **[Contribute to the project](docs/contributing.md)** - Help make it even better
461
+ 7. **[Report issues on GitHub](https://github.com/fluffypony/mcp-code-indexer/issues)** - Share feedback and suggestions
346
462
 
347
463
  ## 🤝 Contributing
348
464
 
@@ -361,8 +477,14 @@ MIT License - see **[LICENSE](LICENSE)** for details.
361
477
  - **[Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk)** - The foundation for tool integration
362
478
  - **[tiktoken](https://pypi.org/project/tiktoken/)** - Fast BPE tokenization
363
479
  - **[aiosqlite](https://pypi.org/project/aiosqlite/)** - Async SQLite operations
480
+ - **[aiohttp](https://pypi.org/project/aiohttp/)** - Async HTTP client for OpenRouter API
481
+ - **[tenacity](https://pypi.org/project/tenacity/)** - Robust retry logic and rate limiting
364
482
  - **[Pydantic](https://pydantic.dev/)** - Data validation and settings
365
483
 
366
484
  ---
367
485
 
368
- **Ready to supercharge your AI agents with intelligent codebase navigation?** 🚀 [Install from PyPI](#install-from-pypi) or [explore the API docs](docs/api-reference.md)!
486
+ **Transform how your AI agents understand code!** 🚀
487
+
488
+ 🎯 **New User?** [Get started in 2 minutes](#-quick-start)
489
+ 👨‍💻 **Developer?** [Explore the complete API](docs/api-reference.md)
490
+ 🔧 **Production?** [Deploy with confidence](docs/configuration.md)
{mcp_code_indexer-1.2.3 → mcp_code_indexer-1.4.0}/README.md RENAMED
@@ -1,10 +1,10 @@
1
1
  # MCP Code Indexer 🚀
2
2
 
3
- [![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?1)](https://badge.fury.io/py/mcp-code-indexer)
4
- [![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?1)](https://pypi.org/project/mcp-code-indexer/)
3
+ [![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?2)](https://badge.fury.io/py/mcp-code-indexer)
4
+ [![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?2)](https://pypi.org/project/mcp-code-indexer/)
5
5
  [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
6
6
 
7
- A production-ready **Model Context Protocol (MCP) server** that provides intelligent codebase navigation for AI agents through searchable file descriptions, token-aware overviews, and advanced merge capabilities.
7
+ A production-ready **Model Context Protocol (MCP) server** that revolutionizes how AI agents navigate and understand codebases. Instead of repeatedly scanning files, agents get instant access to intelligent descriptions, semantic search, and context-aware recommendations.
8
8
 
9
9
  ## 🎯 What It Does
10
10
 
@@ -20,40 +20,107 @@ Perfect for AI-powered code review, refactoring tools, documentation generation,
20
20
 
21
21
  ## ⚡ Quick Start
22
22
 
23
- ### Install from PyPI
23
+ ### 👨‍💻 For Developers
24
+
25
+ Get started integrating MCP Code Indexer into your AI agent workflow:
24
26
 
25
27
  ```bash
26
28
  # Install the package
27
29
  pip install mcp-code-indexer
28
30
 
29
- # Run the server
30
- mcp-code-indexer --token-limit 32000
31
+ # Start the MCP server
32
+ mcp-code-indexer
33
+
34
+ # Connect your MCP client and start using tools
35
+ # See API Reference for complete tool documentation
36
+ ```
37
+
38
+ ### 🔧 For System Administrators
31
39
 
32
- # Check version
40
+ Deploy and configure the server for your team:
41
+
42
+ ```bash
43
+ # Production deployment with custom settings
44
+ mcp-code-indexer \
45
+ --token-limit 64000 \
46
+ --db-path /data/mcp-index.db \
47
+ --cache-dir /var/cache/mcp \
48
+ --log-level INFO
49
+
50
+ # Check installation
33
51
  mcp-code-indexer --version
34
52
  ```
35
53
 
36
- ### Install from Source
54
+ ### 🎯 For Everyone
55
+
56
+ **New to MCP Code Indexer?** Start here:
57
+
58
+ 1. **Install**: `pip install mcp-code-indexer`
59
+ 2. **Run**: `mcp-code-indexer --token-limit 32000`
60
+ 3. **Connect**: Use your favorite MCP client
61
+ 4. **Explore**: Try the `check_codebase_size` tool first
62
+
63
+ **Development Setup**:
37
64
 
38
65
  ```bash
39
- # Clone and setup
40
- git clone https://github.com/your-username/mcp-code-indexer.git
66
+ # Clone and setup for contributing
67
+ git clone https://github.com/fluffypony/mcp-code-indexer.git
41
68
  cd mcp-code-indexer
42
69
 
43
- # Install in development mode
70
+ # Install in development mode (required)
44
71
  pip install -e .
45
72
 
46
73
  # Run the server
47
74
  mcp-code-indexer --token-limit 32000
48
75
  ```
49
76
 
77
+ ## 🔗 Git Hook Integration
78
+
79
+ 🚀 **NEW Feature**: Automated code indexing with AI-powered analysis! Keep your file descriptions synchronized automatically as your codebase evolves.
80
+
81
+ ### 👤 For Users: Quick Setup
82
+
83
+ ```bash
84
+ # Set your OpenRouter API key
85
+ export OPENROUTER_API_KEY="sk-or-v1-your-api-key-here"
86
+
87
+ # Test git hook functionality
88
+ mcp-code-indexer --githook
89
+
90
+ # Install post-commit hook
91
+ cp examples/git-hooks/post-commit .git/hooks/
92
+ chmod +x .git/hooks/post-commit
93
+ ```
94
+
95
+ ### 👨‍💻 For Developers: How It Works
96
+
97
+ The git hook integration provides intelligent automation:
98
+
99
+ - **📊 Git Analysis**: Automatically analyzes git diffs after commits/merges
100
+ - **🤖 AI Processing**: Uses OpenRouter API with Anthropic's Claude Sonnet 4
101
+ - **⚡ Smart Updates**: Only processes files that actually changed
102
+ - **🔄 Overview Maintenance**: Updates project overview when structure changes
103
+ - **🛡️ Error Isolation**: Git operations continue even if indexing fails
104
+ - **⏱️ Rate Limiting**: Built-in retry logic with exponential backoff
105
+
106
+ ### 🎯 Key Benefits
107
+
108
+ 💡 **Zero Manual Work**: Descriptions stay current without any effort
109
+ ⚡ **Performance**: Only analyzes changed files, not entire codebase
110
+ 🔒 **Reliability**: Robust error handling ensures git operations never fail
111
+ 🎛️ **Configurable**: Support for custom models and timeout settings
112
+
113
+ **Learn More**: See [Git Hook Setup Guide](docs/git-hook-setup.md) for complete configuration options and troubleshooting.
114
+
50
115
  ## 🔧 Development Setup
51
116
 
52
- For development work, you **must** install the package in editable mode to ensure proper import resolution:
117
+ ### 👨‍💻 For Contributors
118
+
119
+ Contributing to MCP Code Indexer? Follow these steps for a proper development environment:
53
120
 
54
121
  ```bash
55
122
  # Setup development environment
56
- git clone https://github.com/your-username/mcp-code-indexer.git
123
+ git clone https://github.com/fluffypony/mcp-code-indexer.git
57
124
  cd mcp-code-indexer
58
125
 
59
126
  # Create and activate virtual environment
@@ -71,11 +138,9 @@ python main.py --help
71
138
  mcp-code-indexer --version
72
139
  ```
73
140
 
74
- ### Why Editable Install is Required
75
-
76
- The project uses a proper PyPI package structure with absolute imports like `from mcp_code_indexer.database.database import DatabaseManager`. Without the editable installation (`pip install -e .`), Python cannot resolve these imports and you'll get `ModuleNotFoundError` exceptions.
141
+ ⚠️ **Important**: The editable install (`pip install -e .`) is **required** for development. The project uses proper PyPI package structure with absolute imports like `from mcp_code_indexer.database.database import DatabaseManager`. Without editable installation, you'll get `ModuleNotFoundError` exceptions.
77
142
 
78
- ### Development Workflow
143
+ ### 🎯 Development Workflow
79
144
 
80
145
  ```bash
81
146
  # Activate virtual environment
@@ -103,27 +168,27 @@ mypy src/
103
168
 
104
169
  ## 🛠️ MCP Tools Available
105
170
 
106
- The server provides **11 powerful MCP tools** for intelligent codebase management:
171
+ The server provides **11 powerful MCP tools** for intelligent codebase management. Whether you're an AI agent or human developer, these tools make navigating code effortless.
107
172
 
108
- ### Core Operations
109
- - **`get_file_description`** - Retrieve stored file descriptions instantly
110
- - **`update_file_description`** - Store detailed file summaries and metadata
111
- - **`check_codebase_size`** - Get token count and size-based recommendations with automatic file cleanup
173
+ ### 🎯 For Everyone: Start Here
174
+ - **`check_codebase_size`** - Get instant recommendations for how to navigate your codebase
175
+ - **`search_descriptions`** - Find files by what they do, not just their names
176
+ - **`get_codebase_overview`** - Get a high-level understanding of any project
112
177
 
113
- ### Batch Operations
178
+ ### 👨‍💻 For Developers: Core Operations
179
+ - **`get_file_description`** - Retrieve stored file descriptions instantly
180
+ - **`update_file_description`** - Store detailed file summaries and metadata
114
181
  - **`find_missing_descriptions`** - Scan projects for files without descriptions
115
182
  - **`update_missing_descriptions`** - Bulk update multiple file descriptions
116
183
 
117
- ### Search & Discovery
118
- - **`search_descriptions`** - Fast full-text search across all descriptions
184
+ ### 🔍 For Advanced Users: Search & Discovery
119
185
  - **`get_all_descriptions`** - Complete hierarchical project structure
120
- - **`get_codebase_overview`** - Condensed narrative overview of entire codebase
121
186
  - **`get_word_frequency`** - Technical vocabulary analysis with stop-word filtering
122
-
123
- ### Advanced Features
124
187
  - **`merge_branch_descriptions`** - Two-phase merge with conflict resolution
125
188
  - **`update_codebase_overview`** - Create comprehensive codebase documentation
126
189
 
190
+ 💡 **Pro Tip**: Always start with `check_codebase_size` to get personalized recommendations for navigating your specific codebase.
191
+
127
192
  ## 🏗️ Architecture Highlights
128
193
 
129
194
  ### Performance Optimized
@@ -147,10 +212,16 @@ The server provides **11 powerful MCP tools** for intelligent codebase managemen
147
212
 
148
213
  ## 📖 Documentation
149
214
 
150
- - **[API Reference](docs/api-reference.md)** - Complete MCP tool documentation
151
- - **[Configuration Guide](docs/configuration.md)** - Setup and tuning options
152
- - **[Architecture Overview](docs/architecture.md)** - Technical deep dive
153
- - **[Contributing Guide](docs/contributing.md)** - Development workflow
215
+ ### 👤 For Users
216
+ - **[Git Hook Setup Guide](docs/git-hook-setup.md)** - Automated code indexing setup
217
+ - **[Configuration Guide](docs/configuration.md)** - Production deployment and tuning
218
+
219
+ ### 👨‍💻 For Developers
220
+ - **[API Reference](docs/api-reference.md)** - Complete MCP tool documentation with examples
221
+ - **[Architecture Overview](docs/architecture.md)** - Technical deep dive into system design
222
+
223
+ ### 🤝 For Contributors
224
+ - **[Contributing Guide](docs/contributing.md)** - Development setup and workflow guidelines
154
225
 
155
226
  ## 🚦 System Requirements
156
227
 
@@ -274,6 +345,39 @@ The server provides structured JSON logs for monitoring:
274
345
  }
275
346
  ```
276
347
 
348
+ ## 📋 Command Line Options
349
+
350
+ ### Server Mode (Default)
351
+ ```bash
352
+ mcp-code-indexer [OPTIONS]
353
+
354
+ Options:
355
+ --token-limit INT Maximum tokens before recommending search (default: 32000)
356
+ --db-path PATH SQLite database path (default: ~/.mcp-code-index/tracker.db)
357
+ --cache-dir PATH Cache directory path (default: ~/.mcp-code-index/cache)
358
+ --log-level LEVEL Logging level: DEBUG|INFO|WARNING|ERROR|CRITICAL (default: INFO)
359
+ ```
360
+
361
+ ### Git Hook Mode
362
+ ```bash
363
+ mcp-code-indexer --githook [OPTIONS]
364
+
365
+ # Automated analysis of git changes using OpenRouter API
366
+ # Requires: OPENROUTER_API_KEY environment variable
367
+ ```
368
+
369
+ ### Utility Commands
370
+ ```bash
371
+ # List all projects and branches
372
+ mcp-code-indexer --getprojects
373
+
374
+ # Execute MCP tool directly
375
+ mcp-code-indexer --runcommand '{"method": "tools/call", "params": {...}}'
376
+
377
+ # Export descriptions for a project
378
+ mcp-code-indexer --dumpdescriptions PROJECT_ID [BRANCH]
379
+ ```
380
+
277
381
  ## 🛡️ Security Features
278
382
 
279
383
  - **Input validation** on all MCP tool parameters
@@ -284,10 +388,20 @@ The server provides structured JSON logs for monitoring:
284
388
 
285
389
  ## 🚀 Next Steps
286
390
 
287
- 1. **[Read the API docs](docs/api-reference.md)** to understand available tools
288
- 2. **[Check the configuration guide](docs/configuration.md)** for advanced setup
289
- 3. **[Review the architecture](docs/architecture.md)** for technical details
290
- 4. **[Contribute](docs/contributing.md)** to help improve the project
391
+ Ready to supercharge your AI agents with intelligent codebase navigation?
392
+
393
+ ### 👤 Getting Started
394
+ 1. **[Install and run your first server](#-quick-start)** - Get up and running in 2 minutes
395
+ 2. **[Set up git hooks](docs/git-hook-setup.md)** - Automate your workflow
396
+ 3. **[Configure for production](docs/configuration.md)** - Deploy for your team
397
+
398
+ ### 👨‍💻 For Developers
399
+ 4. **[Explore the API tools](docs/api-reference.md)** - Master all 11 MCP tools
400
+ 5. **[Understand the architecture](docs/architecture.md)** - Deep dive into the technical design
401
+
402
+ ### 🤝 Join the Community
403
+ 6. **[Contribute to the project](docs/contributing.md)** - Help make it even better
404
+ 7. **[Report issues on GitHub](https://github.com/fluffypony/mcp-code-indexer/issues)** - Share feedback and suggestions
291
405
 
292
406
  ## 🤝 Contributing
293
407
 
@@ -306,8 +420,14 @@ MIT License - see **[LICENSE](LICENSE)** for details.
306
420
  - **[Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk)** - The foundation for tool integration
307
421
  - **[tiktoken](https://pypi.org/project/tiktoken/)** - Fast BPE tokenization
308
422
  - **[aiosqlite](https://pypi.org/project/aiosqlite/)** - Async SQLite operations
423
+ - **[aiohttp](https://pypi.org/project/aiohttp/)** - Async HTTP client for OpenRouter API
424
+ - **[tenacity](https://pypi.org/project/tenacity/)** - Robust retry logic and rate limiting
309
425
  - **[Pydantic](https://pydantic.dev/)** - Data validation and settings
310
426
 
311
427
  ---
312
428
 
313
- **Ready to supercharge your AI agents with intelligent codebase navigation?** 🚀 [Install from PyPI](#install-from-pypi) or [explore the API docs](docs/api-reference.md)!
429
+ **Transform how your AI agents understand code!** 🚀
430
+
431
+ 🎯 **New User?** [Get started in 2 minutes](#-quick-start)
432
+ 👨‍💻 **Developer?** [Explore the complete API](docs/api-reference.md)
433
+ 🔧 **Production?** [Deploy with confidence](docs/configuration.md)