cicada-mcp 0.1.4__py3-none-any.whl
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.
Potentially problematic release.
This version of cicada-mcp might be problematic. Click here for more details.
- cicada/__init__.py +30 -0
- cicada/clean.py +297 -0
- cicada/command_logger.py +293 -0
- cicada/dead_code_analyzer.py +282 -0
- cicada/extractors/__init__.py +36 -0
- cicada/extractors/base.py +66 -0
- cicada/extractors/call.py +176 -0
- cicada/extractors/dependency.py +361 -0
- cicada/extractors/doc.py +179 -0
- cicada/extractors/function.py +246 -0
- cicada/extractors/module.py +123 -0
- cicada/extractors/spec.py +151 -0
- cicada/find_dead_code.py +270 -0
- cicada/formatter.py +918 -0
- cicada/git_helper.py +646 -0
- cicada/indexer.py +629 -0
- cicada/install.py +724 -0
- cicada/keyword_extractor.py +364 -0
- cicada/keyword_search.py +553 -0
- cicada/lightweight_keyword_extractor.py +298 -0
- cicada/mcp_server.py +1559 -0
- cicada/mcp_tools.py +291 -0
- cicada/parser.py +124 -0
- cicada/pr_finder.py +435 -0
- cicada/pr_indexer/__init__.py +20 -0
- cicada/pr_indexer/cli.py +62 -0
- cicada/pr_indexer/github_api_client.py +431 -0
- cicada/pr_indexer/indexer.py +297 -0
- cicada/pr_indexer/line_mapper.py +209 -0
- cicada/pr_indexer/pr_index_builder.py +253 -0
- cicada/setup.py +339 -0
- cicada/utils/__init__.py +52 -0
- cicada/utils/call_site_formatter.py +95 -0
- cicada/utils/function_grouper.py +57 -0
- cicada/utils/hash_utils.py +173 -0
- cicada/utils/index_utils.py +290 -0
- cicada/utils/path_utils.py +240 -0
- cicada/utils/signature_builder.py +106 -0
- cicada/utils/storage.py +111 -0
- cicada/utils/subprocess_runner.py +182 -0
- cicada/utils/text_utils.py +90 -0
- cicada/version_check.py +116 -0
- cicada_mcp-0.1.4.dist-info/METADATA +619 -0
- cicada_mcp-0.1.4.dist-info/RECORD +48 -0
- cicada_mcp-0.1.4.dist-info/WHEEL +5 -0
- cicada_mcp-0.1.4.dist-info/entry_points.txt +8 -0
- cicada_mcp-0.1.4.dist-info/licenses/LICENSE +21 -0
- cicada_mcp-0.1.4.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,619 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: cicada-mcp
|
|
3
|
+
Version: 0.1.4
|
|
4
|
+
Summary: An Elixir module search MCP server
|
|
5
|
+
Author-email: wende <wende@hey.com>
|
|
6
|
+
Maintainer-email: wende <wende@hey.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
Project-URL: Homepage, https://github.com/wende/cicada
|
|
9
|
+
Project-URL: Repository, https://github.com/wende/cicada
|
|
10
|
+
Project-URL: Issues, https://github.com/wende/cicada/issues
|
|
11
|
+
Project-URL: Changelog, https://github.com/wende/cicada/blob/main/CHANGELOG.md
|
|
12
|
+
Project-URL: Documentation, https://github.com/wende/cicada#readme
|
|
13
|
+
Keywords: elixir,phoenix,mcp,model-context-protocol,code-search,developer-tools,git-history,code-intelligence,ai-assistant
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Topic :: Software Development :: Code Generators
|
|
22
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
23
|
+
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
24
|
+
Classifier: Topic :: Text Processing :: Indexing
|
|
25
|
+
Classifier: Framework :: Pytest
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
Requires-Dist: mcp>=0.1.0
|
|
30
|
+
Requires-Dist: pyyaml>=6.0
|
|
31
|
+
Requires-Dist: tree-sitter>=0.20.0
|
|
32
|
+
Requires-Dist: tree-sitter-elixir>=0.1.0
|
|
33
|
+
Requires-Dist: gitpython>=3.1.0
|
|
34
|
+
Requires-Dist: lemminflect>=0.2.3
|
|
35
|
+
Requires-Dist: rank-bm25>=0.2.2
|
|
36
|
+
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
|
|
37
|
+
Provides-Extra: dev
|
|
38
|
+
Requires-Dist: pytest>=8.0.0; extra == "dev"
|
|
39
|
+
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
|
|
40
|
+
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
|
|
41
|
+
Requires-Dist: black>=24.0.0; extra == "dev"
|
|
42
|
+
Requires-Dist: pyrefly>=0.1.0; extra == "dev"
|
|
43
|
+
Dynamic: license-file
|
|
44
|
+
|
|
45
|
+
<div align="center">
|
|
46
|
+
|
|
47
|
+
<img src="https://raw.githubusercontent.com/wende/cicada/main/public/cicada.png" alt="CICADA Logo" width="400"/>
|
|
48
|
+
|
|
49
|
+
# CICADA
|
|
50
|
+
|
|
51
|
+
### **C**ode **I**ntelligence: **C**ontextual **A**nalysis, **D**iscovery, and **A**ttribution
|
|
52
|
+
|
|
53
|
+
*Coding Agents search blindly. Be their guide.*
|
|
54
|
+
|
|
55
|
+
[](https://www.python.org/downloads/)
|
|
56
|
+
[](https://opensource.org/licenses/MIT)
|
|
57
|
+
[](https://codecov.io/gh/wende/cicada)
|
|
58
|
+
[](https://modelcontextprotocol.io)
|
|
59
|
+
[](https://github.com/psf/black)
|
|
60
|
+
[](https://elixir-lang.org/)
|
|
61
|
+
[](http://makeapullrequest.com)
|
|
62
|
+
|
|
63
|
+
[](https://cursor.com/en-US/install-mcp?name=cicada&config=eyJjb21tYW5kIjoidXZ4IC0tZnJvbSBnaXQraHR0cHM6Ly9naXRodWIuY29tL3dlbmRlL2NpY2FkYS5naXRAbGF0ZXN0IGNpY2FkYS1zZXJ2ZXIgLiJ9)
|
|
64
|
+
|
|
65
|
+
[Installation](#installation) •
|
|
66
|
+
[Quick Start](#quick-start) •
|
|
67
|
+
[Configuration](#configuration) •
|
|
68
|
+
[MCP Tools](#mcp-tools) •
|
|
69
|
+
[Contributing](#contributing)
|
|
70
|
+
|
|
71
|
+
</div>
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Overview
|
|
76
|
+
|
|
77
|
+
CICADA is a Model Context Protocol (MCP) server that provides AI coding assistants with deep code intelligence. **Currently supports Elixir projects**, with Python and TypeScript support planned for future releases. It indexes your codebase using tree-sitter AST parsing and provides instant access to modules, functions, call sites, and PR attribution.
|
|
78
|
+
|
|
79
|
+
<div align="center">
|
|
80
|
+
<table>
|
|
81
|
+
<tr>
|
|
82
|
+
<td align="center"><b>Without CICADA</b></td>
|
|
83
|
+
<td align="center"><b>With CICADA</b></td>
|
|
84
|
+
</tr>
|
|
85
|
+
<tr>
|
|
86
|
+
<td><img src="https://raw.githubusercontent.com/wende/cicada/main/public/no-cicada-demo-trimmed.gif" alt="Demo without CICADA" width="450"/></td>
|
|
87
|
+
<td><img src="https://raw.githubusercontent.com/wende/cicada/main/public/cicada-demo-extended-clean-trimmed%20copy.gif" alt="Demo with CICADA" width="450"/></td>
|
|
88
|
+
</tr>
|
|
89
|
+
<tr>
|
|
90
|
+
<td align="center">3,127 tokens • 52.84s</td>
|
|
91
|
+
<td align="center">550 tokens • 35.04s</td>
|
|
92
|
+
</tr>
|
|
93
|
+
<tr>
|
|
94
|
+
<td colspan="2" align="center"><b>82.4% fewer tokens • 33.7% faster</b></td>
|
|
95
|
+
</tr>
|
|
96
|
+
</table>
|
|
97
|
+
</div>
|
|
98
|
+
|
|
99
|
+
### Key Features
|
|
100
|
+
|
|
101
|
+
- **AST-aware code search** - Find function definitions with full signatures, types, and documentation—no implementation bloat
|
|
102
|
+
- **Intelligent call site tracking** - Resolve aliases and track where functions are actually invoked across the codebase
|
|
103
|
+
- **PR attribution & review context** - Discover which pull request introduced any line and view historical code review discussions inline
|
|
104
|
+
- **Function evolution tracking** - See when functions were created, how often they’re modified, and their complete git history
|
|
105
|
+
- **Semantic module analysis** - Understand module dependencies, imports, and relationships beyond text matching
|
|
106
|
+
- **MCP integration** - Provide AI coding assistants with structured code intelligence, not raw text
|
|
107
|
+
|
|
108
|
+
## Installation
|
|
109
|
+
|
|
110
|
+
### Recommended: Permanent Installation
|
|
111
|
+
|
|
112
|
+
**Installing UV:**
|
|
113
|
+
```bash
|
|
114
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
115
|
+
# or: brew install uv
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
**Install Cicada permanently for best experience:**
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
# Step 1: Install once
|
|
122
|
+
uv tool install git+https://github.com/wende/cicada.git@latest
|
|
123
|
+
|
|
124
|
+
# Step 2: Setup in each project (one command per project)
|
|
125
|
+
cd /path/to/your/elixir/project
|
|
126
|
+
cicada claude # or: cicada cursor, cicada vs
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
**That's it!** The setup command:
|
|
130
|
+
- Indexes your codebase with keyword extraction
|
|
131
|
+
- Stores all files in `~/.cicada/projects/<hash>/` (outside your repo)
|
|
132
|
+
- Creates only an MCP config file in your repo (`.mcp.json` for Claude Code)
|
|
133
|
+
- Configures the MCP server automatically
|
|
134
|
+
|
|
135
|
+
**After setup:**
|
|
136
|
+
1. Restart your editor
|
|
137
|
+
2. Start coding with AI-powered Elixir intelligence!
|
|
138
|
+
|
|
139
|
+
**Available commands after installation:**
|
|
140
|
+
- `cicada [claude|cursor|vs]` - One-command setup per project
|
|
141
|
+
- `cicada-server` - MCP server (auto-started by editor)
|
|
142
|
+
- `cicada-index` - Re-index code with custom options (medium/large spaCy models)
|
|
143
|
+
- `cicada-index-pr` - Index pull requests for PR attribution
|
|
144
|
+
- `cicada-install` - Legacy setup (creates `.cicada/` in repo)
|
|
145
|
+
|
|
146
|
+
### Try Before Installing
|
|
147
|
+
|
|
148
|
+
Want to test Cicada first? Use `uvx` for a quick trial:
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
cd /path/to/your/elixir/project
|
|
152
|
+
|
|
153
|
+
# For Claude Code
|
|
154
|
+
uvx --from git+https://github.com/wende/cicada.git@latest cicada claude
|
|
155
|
+
|
|
156
|
+
# For Cursor
|
|
157
|
+
uvx --from git+https://github.com/wende/cicada.git@latest cicada cursor
|
|
158
|
+
|
|
159
|
+
# For VS Code
|
|
160
|
+
uvx --from git+https://github.com/wende/cicada.git@latest cicada vs
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
**Note:** `uvx` is perfect for trying Cicada, but **permanent installation is recommended** because:
|
|
164
|
+
- ✅ Faster MCP server startup (no temporary environment creation)
|
|
165
|
+
- ✅ Access to all CLI commands (`cicada-index`, `cicada-index-pr`)
|
|
166
|
+
- ✅ Fine-tuned keyword extraction with medium/large spaCy models
|
|
167
|
+
- ✅ PR indexing features
|
|
168
|
+
- ✅ Custom re-indexing options
|
|
169
|
+
|
|
170
|
+
Once you're convinced, install permanently with `uv tool install` above!
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## Quick Start
|
|
175
|
+
|
|
176
|
+
After installation, ask your AI coding assistant:
|
|
177
|
+
|
|
178
|
+
```
|
|
179
|
+
"What functions are in the MyApp.User module?"
|
|
180
|
+
"Show me where authenticate/2 is called"
|
|
181
|
+
"Which PR introduced line 42 of user.ex?"
|
|
182
|
+
"Show me all PRs that modified the User module with their review comments"
|
|
183
|
+
"Find all usages of Repo.insert/2"
|
|
184
|
+
"What's the git history of the authenticate function?"
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
**For PR features**, first run:
|
|
188
|
+
```bash
|
|
189
|
+
cicada-index-pr .
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## Configuration
|
|
195
|
+
|
|
196
|
+
### Automatic Configuration
|
|
197
|
+
|
|
198
|
+
The new simplified workflow stores all generated files outside your repository:
|
|
199
|
+
|
|
200
|
+
**Storage Structure:**
|
|
201
|
+
```
|
|
202
|
+
~/.cicada/
|
|
203
|
+
projects/
|
|
204
|
+
<repo-hash>/
|
|
205
|
+
config.yaml # MCP server configuration
|
|
206
|
+
index.json # Code index with keywords
|
|
207
|
+
pr_index.json # PR attribution data (optional)
|
|
208
|
+
hashes.json # For incremental indexing
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
**Your Repository (Clean!):**
|
|
212
|
+
```
|
|
213
|
+
your-project/
|
|
214
|
+
.mcp.json # Only this file is added (for Claude Code)
|
|
215
|
+
# or .cursor/mcp.json for Cursor
|
|
216
|
+
# or .vscode/settings.json for VS Code
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
**Generated MCP Config (Claude Code example):**
|
|
220
|
+
```json
|
|
221
|
+
{
|
|
222
|
+
"mcpServers": {
|
|
223
|
+
"cicada": {
|
|
224
|
+
"command": "cicada-server",
|
|
225
|
+
"env": {
|
|
226
|
+
"CICADA_REPO_PATH": "/path/to/project",
|
|
227
|
+
"CICADA_CONFIG_DIR": "/home/user/.cicada/projects/<hash>"
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
### Re-indexing
|
|
235
|
+
|
|
236
|
+
After code changes, re-run the setup command:
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
# Re-index for Claude Code
|
|
240
|
+
uvx --from git+https://github.com/wende/cicada.git@latest cicada claude
|
|
241
|
+
|
|
242
|
+
# Or if permanently installed
|
|
243
|
+
cicada claude
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
This will:
|
|
247
|
+
- Detect changed files (incremental indexing)
|
|
248
|
+
- Update the index with new/modified code
|
|
249
|
+
- Keep your existing MCP configuration
|
|
250
|
+
|
|
251
|
+
### Optional: PR Attribution
|
|
252
|
+
|
|
253
|
+
Index pull requests for PR-related features:
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
# After permanent installation
|
|
257
|
+
cicada-index-pr .
|
|
258
|
+
|
|
259
|
+
# Or with uvx
|
|
260
|
+
uvx --from git+https://github.com/wende/cicada.git@latest cicada-index-pr .
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### Legacy Installation
|
|
264
|
+
|
|
265
|
+
If you prefer the old setup (stores files in `.cicada/` directory in your repo):
|
|
266
|
+
|
|
267
|
+
```bash
|
|
268
|
+
# Only available after permanent installation
|
|
269
|
+
cicada-install
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
**See also:** [PR Indexing Documentation](docs/PR_INDEXING.md)
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## MCP Tools
|
|
277
|
+
|
|
278
|
+
CICADA provides 9 specialized tools for AI assistants to understand and navigate your codebase. For complete technical documentation including parameters and return formats, see [MCP Tools Reference](docs/MCP-Tools-Reference.md).
|
|
279
|
+
|
|
280
|
+
### Core Search Tools
|
|
281
|
+
|
|
282
|
+
**`search_module`** - Find modules and view all their functions
|
|
283
|
+
- Search by exact module name or file path
|
|
284
|
+
- View function signatures with type specs
|
|
285
|
+
- Filter public/private functions
|
|
286
|
+
- Output in Markdown or JSON
|
|
287
|
+
|
|
288
|
+
**`search_function`** - Locate function definitions and track usage
|
|
289
|
+
- Search by function name, arity, or full module path
|
|
290
|
+
- See where functions are called with line numbers
|
|
291
|
+
- View actual code usage examples
|
|
292
|
+
- Filter for test files only
|
|
293
|
+
|
|
294
|
+
**`search_module_usage`** - Track module dependencies
|
|
295
|
+
- Find all aliases and imports
|
|
296
|
+
- See all function calls to a module
|
|
297
|
+
- Understand module relationships
|
|
298
|
+
- Map dependencies across codebase
|
|
299
|
+
|
|
300
|
+
### Git History & Attribution Tools
|
|
301
|
+
|
|
302
|
+
**`find_pr_for_line`** - Identify which PR introduced any line of code
|
|
303
|
+
- Line-level PR attribution via git blame
|
|
304
|
+
- Author and commit information
|
|
305
|
+
- Direct links to GitHub PRs
|
|
306
|
+
- Requires: GitHub CLI + PR index
|
|
307
|
+
|
|
308
|
+
**`get_file_pr_history`** - View complete PR history for a file
|
|
309
|
+
- All PRs that modified the file
|
|
310
|
+
- PR descriptions and metadata
|
|
311
|
+
- Code review comments with line numbers
|
|
312
|
+
- Requires: GitHub CLI + PR index
|
|
313
|
+
|
|
314
|
+
**`get_commit_history`** - Track file and function evolution over time
|
|
315
|
+
- Complete commit history for files
|
|
316
|
+
- Function-level tracking (follows refactors)
|
|
317
|
+
- Creation and modification timeline
|
|
318
|
+
- Requires: `.gitattributes` configuration
|
|
319
|
+
|
|
320
|
+
**`get_blame`** - Show line-by-line code ownership
|
|
321
|
+
- Grouped authorship display
|
|
322
|
+
- Commit details for each author
|
|
323
|
+
- Code snippets with context
|
|
324
|
+
|
|
325
|
+
### Advanced Features
|
|
326
|
+
|
|
327
|
+
**`search_by_keywords`** (EXPERIMENTAL) - Semantic documentation search
|
|
328
|
+
- Find code by concepts, not just names
|
|
329
|
+
- Wildcard pattern matching (`create*`, `*_user`)
|
|
330
|
+
- NLP-extracted keywords from docs
|
|
331
|
+
- Relevance scoring
|
|
332
|
+
- Requires: Index built with `--extract-keywords`
|
|
333
|
+
|
|
334
|
+
**`find_dead_code`** - Identify potentially unused functions
|
|
335
|
+
- Three confidence levels (high, medium, low)
|
|
336
|
+
- Smart detection of callbacks and behaviors
|
|
337
|
+
- Recognition of dynamic call patterns
|
|
338
|
+
- Module-level grouping with line numbers
|
|
339
|
+
- Excludes test files and `@impl` functions
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
**See also:** [Complete MCP Tools Reference](docs/MCP-Tools-Reference.md) for detailed specifications
|
|
344
|
+
|
|
345
|
+
---
|
|
346
|
+
|
|
347
|
+
## CLI Tools
|
|
348
|
+
|
|
349
|
+
CICADA provides several command-line tools for setup, indexing, and analysis:
|
|
350
|
+
|
|
351
|
+
### Setup & Configuration
|
|
352
|
+
|
|
353
|
+
**`cicada`** - Initialize CICADA in your project
|
|
354
|
+
```bash
|
|
355
|
+
cicada # Setup in current directory
|
|
356
|
+
cicada --skip-install # Skip dependency installation
|
|
357
|
+
cicada /path/to/other/project # Setup in different directory
|
|
358
|
+
```
|
|
359
|
+
- Generates `.mcp.json` configuration
|
|
360
|
+
- Creates `.cicada/` directory
|
|
361
|
+
- Installs Elixir dependencies
|
|
362
|
+
- Configures git attributes for function tracking
|
|
363
|
+
|
|
364
|
+
### Indexing Tools
|
|
365
|
+
|
|
366
|
+
**`cicada-index`** - Index Elixir codebase
|
|
367
|
+
```bash
|
|
368
|
+
cicada-index # Index current directory
|
|
369
|
+
cicada-index --output .cicada/index.json
|
|
370
|
+
cicada-index --extract-keywords # Include NLP keyword extraction
|
|
371
|
+
```
|
|
372
|
+
- Parses all Elixir files using tree-sitter
|
|
373
|
+
- Extracts modules, functions, and call sites
|
|
374
|
+
- Resolves aliases for accurate tracking
|
|
375
|
+
- Optional keyword extraction for semantic search
|
|
376
|
+
|
|
377
|
+
**`cicada-index-pr`** - Index GitHub pull requests
|
|
378
|
+
```bash
|
|
379
|
+
cicada-index-pr . # Index PRs for current repo
|
|
380
|
+
cicada-index-pr . --clean # Full rebuild from scratch
|
|
381
|
+
```
|
|
382
|
+
- Requires GitHub CLI (`gh`) authenticated
|
|
383
|
+
- Indexes PR metadata and review comments
|
|
384
|
+
- Incremental updates by default
|
|
385
|
+
- Enables PR attribution features
|
|
386
|
+
|
|
387
|
+
### Analysis Tools
|
|
388
|
+
|
|
389
|
+
**`cicada-find-dead-code`** - Find unused functions (CLI version)
|
|
390
|
+
```bash
|
|
391
|
+
cicada-find-dead-code # Show high confidence only
|
|
392
|
+
cicada-find-dead-code --min-confidence low # Show all candidates
|
|
393
|
+
cicada-find-dead-code --format json # JSON output
|
|
394
|
+
cicada-find-dead-code --index path/to/index.json
|
|
395
|
+
```
|
|
396
|
+
- Analyzes function usage across codebase
|
|
397
|
+
- Categorizes by confidence level
|
|
398
|
+
- Available as both CLI tool and MCP tool
|
|
399
|
+
|
|
400
|
+
---
|
|
401
|
+
|
|
402
|
+
## Roadmap
|
|
403
|
+
|
|
404
|
+
### v0.1.1 (Released - October 2025) ✅
|
|
405
|
+
- Module and function search
|
|
406
|
+
- Call site tracking with alias resolution
|
|
407
|
+
- PR attribution via git blame + GitHub
|
|
408
|
+
- PR review comments with line mapping
|
|
409
|
+
- File PR history with descriptions
|
|
410
|
+
- GraphQL-based PR indexing (30x faster)
|
|
411
|
+
- Function usage examples with code snippets
|
|
412
|
+
- Git commit history tracking with precise function tracking
|
|
413
|
+
- Function evolution metadata (creation, modifications, frequency)
|
|
414
|
+
- Git blame integration with line-by-line authorship
|
|
415
|
+
- Test file filtering
|
|
416
|
+
- Multiple output formats (markdown, JSON)
|
|
417
|
+
- Intelligent .mcp.json auto-configuration
|
|
418
|
+
- `uv tool install` support
|
|
419
|
+
- **Automatic version update checking** - Notifies users when newer versions are available
|
|
420
|
+
- **NLP Keyword search** (EXPERIMENTAL) - Semantic search across documentation with wildcard support
|
|
421
|
+
|
|
422
|
+
### v0.2 (Potential Future Enhancements)
|
|
423
|
+
- Incremental code re-indexing
|
|
424
|
+
- Enhanced keyword search with BM25 ranking
|
|
425
|
+
- RAG with KeyBERT option (??)
|
|
426
|
+
|
|
427
|
+
### Long Term (Stretch Goals)
|
|
428
|
+
- Multi-language support (Python, TypeScript)
|
|
429
|
+
- Semantic code search
|
|
430
|
+
- Real-time incremental indexing
|
|
431
|
+
- Web UI for exploration
|
|
432
|
+
|
|
433
|
+
### Out of Scope (Non-Goals)
|
|
434
|
+
These features are explicitly **not planned**:
|
|
435
|
+
- Fuzzy search / "did you mean" suggestions (grep is sufficient)
|
|
436
|
+
- Function similarity algorithms or recommendations
|
|
437
|
+
- Confidence scoring systems
|
|
438
|
+
- Multi-repository support (single repo focus)
|
|
439
|
+
- Alternative function suggestions (bang/non-bang variants)
|
|
440
|
+
|
|
441
|
+
---
|
|
442
|
+
|
|
443
|
+
## Design Decisions
|
|
444
|
+
|
|
445
|
+
CICADA prioritizes simplicity and reliability over complexity:
|
|
446
|
+
|
|
447
|
+
### Intentional Constraints
|
|
448
|
+
- **Exact name matching only** - Use grep/ripgrep for fuzzy searches; keeping CICADA focused
|
|
449
|
+
- **Direct call tracking** - Tracks explicit function calls; comprehensive call graphs add complexity without enough value
|
|
450
|
+
- **Manual documentation search** - Documentation indexing planned for v0.1
|
|
451
|
+
- **No AI/ML features** - No similarity algorithms, confidence scoring, or recommendations; deterministic results only
|
|
452
|
+
|
|
453
|
+
These are deliberate design choices to keep CICADA fast, predictable, and maintainable.
|
|
454
|
+
|
|
455
|
+
---
|
|
456
|
+
|
|
457
|
+
## Contributing
|
|
458
|
+
|
|
459
|
+
### Development Setup
|
|
460
|
+
|
|
461
|
+
```bash
|
|
462
|
+
# Clone your fork
|
|
463
|
+
git clone https://github.com/wende/cicada.git
|
|
464
|
+
cd cicada
|
|
465
|
+
|
|
466
|
+
# Using uv (recommended)
|
|
467
|
+
uv sync
|
|
468
|
+
|
|
469
|
+
# Or traditional venv (legacy)
|
|
470
|
+
python -m venv venv
|
|
471
|
+
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
472
|
+
pip install -e ".[dev]"
|
|
473
|
+
|
|
474
|
+
# Run tests
|
|
475
|
+
pytest
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
### Testing
|
|
479
|
+
|
|
480
|
+
```bash
|
|
481
|
+
# Run all tests
|
|
482
|
+
pytest
|
|
483
|
+
|
|
484
|
+
# Run specific test files
|
|
485
|
+
pytest tests/test_parser.py
|
|
486
|
+
pytest tests/test_search_function.py
|
|
487
|
+
|
|
488
|
+
# Run with coverage (terminal report)
|
|
489
|
+
pytest --cov=cicada --cov-report=term-missing
|
|
490
|
+
|
|
491
|
+
# Generate HTML coverage report
|
|
492
|
+
pytest --cov=cicada --cov-report=html
|
|
493
|
+
# Open htmlcov/index.html in your browser
|
|
494
|
+
|
|
495
|
+
# Run with coverage and see which lines need tests
|
|
496
|
+
pytest --cov=cicada --cov-report=term-missing --cov-report=html
|
|
497
|
+
|
|
498
|
+
# Check coverage and fail if below threshold (e.g., 80%)
|
|
499
|
+
pytest --cov=cicada --cov-fail-under=80
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
### Code Style
|
|
503
|
+
|
|
504
|
+
This project uses:
|
|
505
|
+
- **black** for code formatting
|
|
506
|
+
- **pytest** for testing
|
|
507
|
+
- **type hints** where appropriate
|
|
508
|
+
|
|
509
|
+
Before submitting a PR:
|
|
510
|
+
```bash
|
|
511
|
+
# Format code
|
|
512
|
+
black cicada tests
|
|
513
|
+
|
|
514
|
+
# Run tests
|
|
515
|
+
pytest
|
|
516
|
+
|
|
517
|
+
# Check types (if using mypy)
|
|
518
|
+
mypy cicada
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
### Reporting Issues
|
|
522
|
+
|
|
523
|
+
When reporting bugs or requesting features:
|
|
524
|
+
|
|
525
|
+
1. Check existing [Issues](https://github.com/wende/cicada/issues)
|
|
526
|
+
2. If not found, create a new issue with:
|
|
527
|
+
- Clear description
|
|
528
|
+
- Steps to reproduce (for bugs)
|
|
529
|
+
- Expected vs actual behavior
|
|
530
|
+
- Your environment (OS, Python version, Elixir version)
|
|
531
|
+
|
|
532
|
+
---
|
|
533
|
+
|
|
534
|
+
## Troubleshooting
|
|
535
|
+
|
|
536
|
+
### "Index file not found"
|
|
537
|
+
|
|
538
|
+
Run the indexer first:
|
|
539
|
+
```bash
|
|
540
|
+
cicada-index /path/to/project
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
### "Module not found"
|
|
544
|
+
|
|
545
|
+
Use the exact module name as it appears in code (e.g., `MyApp.User`, not `User`).
|
|
546
|
+
|
|
547
|
+
### MCP Server Won't Connect
|
|
548
|
+
|
|
549
|
+
1. Verify `.mcp.json` exists in your project root
|
|
550
|
+
2. Check that all paths in `.mcp.json` are absolute
|
|
551
|
+
3. Ensure `index.json` was created successfully
|
|
552
|
+
4. Restart your MCP client (Claude Code, Cline, etc.)
|
|
553
|
+
5. Check your MCP client logs for errors
|
|
554
|
+
|
|
555
|
+
### PR Features Not Working
|
|
556
|
+
|
|
557
|
+
PR features require the GitHub CLI and a PR index:
|
|
558
|
+
|
|
559
|
+
```bash
|
|
560
|
+
# Install GitHub CLI
|
|
561
|
+
brew install gh # macOS
|
|
562
|
+
# or visit https://cli.github.com/
|
|
563
|
+
|
|
564
|
+
# Authenticate
|
|
565
|
+
gh auth login
|
|
566
|
+
|
|
567
|
+
# Index PRs (first time or after new PRs)
|
|
568
|
+
cicada-index-pr .
|
|
569
|
+
|
|
570
|
+
# Clean rebuild (re-index everything from scratch)
|
|
571
|
+
cicada-index-pr . --clean
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
**Common issues:**
|
|
575
|
+
- "No PR index found" → Run `cicada-index-pr .`
|
|
576
|
+
- "Not a GitHub repository" → Ensure repo has GitHub remote
|
|
577
|
+
- Slow indexing → Incremental updates are used by default
|
|
578
|
+
|
|
579
|
+
#### Uninstall
|
|
580
|
+
|
|
581
|
+
Remove CICADA from a project:
|
|
582
|
+
|
|
583
|
+
```bash
|
|
584
|
+
rm -rf .cicada/ .mcp.json
|
|
585
|
+
# Restart your MCP client
|
|
586
|
+
```
|
|
587
|
+
|
|
588
|
+
---
|
|
589
|
+
|
|
590
|
+
## Credits
|
|
591
|
+
|
|
592
|
+
### Built With
|
|
593
|
+
|
|
594
|
+
- [Tree-sitter](https://tree-sitter.github.io/) - Incremental parsing system
|
|
595
|
+
- [tree-sitter-elixir](https://github.com/elixir-lang/tree-sitter-elixir) - Elixir grammar
|
|
596
|
+
- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol
|
|
597
|
+
- [GitHub CLI](https://cli.github.com/) - PR attribution
|
|
598
|
+
|
|
599
|
+
---
|
|
600
|
+
|
|
601
|
+
## License
|
|
602
|
+
|
|
603
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
604
|
+
|
|
605
|
+
---
|
|
606
|
+
|
|
607
|
+
## Acknowledgments
|
|
608
|
+
|
|
609
|
+
- The Anthropic team for Claude Code and MCP
|
|
610
|
+
- The Elixir community for tree-sitter-elixir
|
|
611
|
+
- All contributors who help improve CICADA
|
|
612
|
+
|
|
613
|
+
---
|
|
614
|
+
|
|
615
|
+
<div align="center">
|
|
616
|
+
|
|
617
|
+
**[⬆ back to top](#cicada)**
|
|
618
|
+
|
|
619
|
+
</div>
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
cicada/__init__.py,sha256=065iLRO62_wiCjQSgJUQzCAR48VXp73K9rhcnXHDiBs,749
|
|
2
|
+
cicada/clean.py,sha256=E9mYE9qoYGesKFQHgDK-LyzpB64POU5CU8287xb6FO0,8627
|
|
3
|
+
cicada/command_logger.py,sha256=Z7YX7wwHCzmf5wWsoIZQhTGrGK11GcvdwO0pquvxYEs,9271
|
|
4
|
+
cicada/dead_code_analyzer.py,sha256=hk3kmuFTj3K2HQpLDwrA_7GHrPc4rP9Ecg3OnrFmdh4,10048
|
|
5
|
+
cicada/find_dead_code.py,sha256=xCheicrNbYhLvrPGgqVJJBbf_rAm_gXwnfONDWPnNI0,8288
|
|
6
|
+
cicada/formatter.py,sha256=wwxD1nt1ub7HDeDRGc61JhpmgleNVlp0SfQG9QBgGns,36194
|
|
7
|
+
cicada/git_helper.py,sha256=zhyqSfk90tCwndWYxhh-LxFmqqXB1Wki91uDkZRr7Js,24303
|
|
8
|
+
cicada/indexer.py,sha256=gVj6Jwc-sZgcGZnueqpRqcn4Wu451qo6RVfGuQahaZ4,25249
|
|
9
|
+
cicada/install.py,sha256=mM8hj1_45CkXUFbJd8ve8dqYyIzNY1HhNbVKbseiJ4s,23214
|
|
10
|
+
cicada/keyword_extractor.py,sha256=9oEEU3cwv5prsWYn1P-nNFayArQeXgCFNzx4iaq1qhg,13425
|
|
11
|
+
cicada/keyword_search.py,sha256=pj5zSsYKX-pOeWyGI53ZRAZm91BnrEMHofGNoenoIqQ,21746
|
|
12
|
+
cicada/lightweight_keyword_extractor.py,sha256=KtxcOjLPuoY6EjcWNvHvoZswcg9IoryMfG4EM3_LDMg,9172
|
|
13
|
+
cicada/mcp_server.py,sha256=k_JnwQExgQ-dTAA-MfPTl8G02B9MEmVZJb8fAc_UnPY,60299
|
|
14
|
+
cicada/mcp_tools.py,sha256=LHNyrpztmY0yk1Ysu3_I-ZE7KmngJJ0ukKd-1OJpenA,13805
|
|
15
|
+
cicada/parser.py,sha256=uQlzYnQQicUWU-yF9LgvqDK-83xImzGlZOkjPoov8_I,4022
|
|
16
|
+
cicada/pr_finder.py,sha256=FPSaGe5W4RwPi93VmyoIWcUZIaHLZdHsT7s_WCIvHBM,14214
|
|
17
|
+
cicada/setup.py,sha256=n9hFlK4LmPG7ivCvnburXvD-7sWwZjCvz6sdWRD_d_0,9166
|
|
18
|
+
cicada/version_check.py,sha256=c8BFl--ohKfLZYe_3tX40rKXydTR6FVGWiseGuIvcBk,3181
|
|
19
|
+
cicada/extractors/__init__.py,sha256=Dnm_jjWMGPvaGmt1aZqcgpS964tak4hys5BFOjbCcg8,890
|
|
20
|
+
cicada/extractors/base.py,sha256=reenF-Cngpg1LgueWsddYzGcmtHElSuNv1F5OlZRFpI,2487
|
|
21
|
+
cicada/extractors/call.py,sha256=kDwzfrhM1tEE3kPmlSfnRAY_0WwGXbTwLm51A__4FVI,6086
|
|
22
|
+
cicada/extractors/dependency.py,sha256=4l7i3mFhUdcdP4MDPWBbt3RsFqbGDRIymbj-sMtInpM,13593
|
|
23
|
+
cicada/extractors/doc.py,sha256=dd1aXy0cI4a0OmxSnIvkXG5Eg_NYLqgBJeARoaTRZz4,6660
|
|
24
|
+
cicada/extractors/function.py,sha256=D-jRpU-__IcLmDhBT_GFTksemYi3zVjoiXN9IubnRz8,8585
|
|
25
|
+
cicada/extractors/module.py,sha256=jAsO_yRbfOORQD7NDVHFJ5I4RhQ8V8X0ZLcAeod6Yvs,4523
|
|
26
|
+
cicada/extractors/spec.py,sha256=7i5mq7DImunLzugGrjWoU9rcKakLn9544ZNALpdVA-A,5959
|
|
27
|
+
cicada/pr_indexer/__init__.py,sha256=_pAnhJH0pOrIKNwrTljWPjzgI6BGdc5UPTuut4FRPes,439
|
|
28
|
+
cicada/pr_indexer/cli.py,sha256=BgXUeaHvvSGvsc6sE_lz5CQHsK96KyNKV3zGqqXg43E,1712
|
|
29
|
+
cicada/pr_indexer/github_api_client.py,sha256=jPkxoZjE7uMKTMiTF7zZC-7Q4OZEhAfFYB_MoQpppkY,13940
|
|
30
|
+
cicada/pr_indexer/indexer.py,sha256=RoCBWVagFv9wGRSbhnbN2O9vRNxduf0SesI_lH_-rFQ,10975
|
|
31
|
+
cicada/pr_indexer/line_mapper.py,sha256=8Z6hsPQl7g2pQ75GQZ5eGlOm8Rm04zeYTRINRisGJ68,6859
|
|
32
|
+
cicada/pr_indexer/pr_index_builder.py,sha256=8Yxi6ZO39SU1OV1zHT75FVCDdiglYgZVUgiPRHlxmuQ,8779
|
|
33
|
+
cicada/utils/__init__.py,sha256=ImDpqwBRyLAy4lCovLJ9ZblagNI-wztGSfgL2ycFwJk,1340
|
|
34
|
+
cicada/utils/call_site_formatter.py,sha256=9xtdzp-hHFS2d-nuh1f1vlhvyKPnMmV3noGvwoCuLcc,3452
|
|
35
|
+
cicada/utils/function_grouper.py,sha256=ANXJGtg3sCn9Q3bYUWur5C9Kg84bqpIyKhlVniJnQPo,1824
|
|
36
|
+
cicada/utils/hash_utils.py,sha256=QYs_x1nRkPqDiUTIQTmqBnUqR-4WM-iLcofTUyn9xpY,5581
|
|
37
|
+
cicada/utils/index_utils.py,sha256=fDLynavABd07XNFs_p_722vHUrOHgP8aw2yHP2-mvn4,8502
|
|
38
|
+
cicada/utils/path_utils.py,sha256=YcbQnkJj_CkO3q562NtwqukwwDkgCtoXV2rHxrTGvD8,7013
|
|
39
|
+
cicada/utils/signature_builder.py,sha256=O76JfypSESNncQ_OppCAR7aUDz4ocBNPXEmI9uhdXgY,3483
|
|
40
|
+
cicada/utils/storage.py,sha256=wbw_Ma77v4uevDGTQP06Eu4m5V8IU6GkKUARYWXgj1A,2578
|
|
41
|
+
cicada/utils/subprocess_runner.py,sha256=fibqu_YCCmQPvtTwaDkGkVyhGVSQ6oX235pBYavQW5M,5168
|
|
42
|
+
cicada/utils/text_utils.py,sha256=_lt_65BcAVZa36QrTY84GR8v5m5oxvfPY3tr6PoNaxw,2923
|
|
43
|
+
cicada_mcp-0.1.4.dist-info/licenses/LICENSE,sha256=ijMI5EAN1o3jl676-BOu0ELzlsBr2FqTRzmha9e1lug,1062
|
|
44
|
+
cicada_mcp-0.1.4.dist-info/METADATA,sha256=pj5-4L2Bz3xn6w6r7HJTRwgPCTa-KiLNOUrTPREDLF0,18931
|
|
45
|
+
cicada_mcp-0.1.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
|
|
46
|
+
cicada_mcp-0.1.4.dist-info/entry_points.txt,sha256=DFW2H5na_prQFHRcgcDOkziQCpzykOZuHO5cztoMA2Y,281
|
|
47
|
+
cicada_mcp-0.1.4.dist-info/top_level.txt,sha256=xZCtaMDbCi2CKA5PExum99ZU54IJg5iognV-k44a1W0,7
|
|
48
|
+
cicada_mcp-0.1.4.dist-info/RECORD,,
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
[console_scripts]
|
|
2
|
+
cicada = cicada.setup:main
|
|
3
|
+
cicada-clean = cicada.clean:main
|
|
4
|
+
cicada-find-dead-code = cicada.find_dead_code:main
|
|
5
|
+
cicada-index = cicada.indexer:main
|
|
6
|
+
cicada-index-pr = cicada.pr_indexer:main
|
|
7
|
+
cicada-install = cicada.install:main
|
|
8
|
+
cicada-server = cicada.mcp_server:main
|