contextl 1.1.0 → 1.1.1

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 (2) hide show
  1. package/README.md +57 -78
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,23 +1,26 @@
1
1
  # contextl
2
2
 
3
- > **Context-selection engine for AI coding assistants.**
4
- > Finds the most relevant files in your codebase for a natural-language change request — no LLM, no embeddings, no vector database. Pure graph + text scoring.
3
+ **Architecture intelligence for AI coding agents.**
4
+
5
+ Stop letting your AI agent read your entire codebase to make one small change. `contextl` finds the exact files that matter — using graph theory, not guesswork.
5
6
 
6
7
  ```
7
- "fix the upload error" → [FileUploader.tsx, lib/upload.ts, UploadSection.tsx]
8
+ "fix the broken checkout flow"
9
+ ↓
10
+ components/Checkout.tsx [high confidence]
11
+ lib/api.ts [high confidence]
12
+ types/index.ts [medium confidence]
8
13
  ```
9
14
 
10
- Instead of feeding your entire repo to an AI, `contextl` reduces 5 000 files down to the 5 most relevant ones in milliseconds.
15
+ No LLM. No embeddings. No API keys. No vector database. Pure dependency graph + text scoring — runs entirely on your machine, your code never leaves your laptop.
11
16
 
12
17
  ---
13
18
 
14
- ## Quick start
15
-
16
- **Requires Python 3.9+** on your PATH. Everything else (`networkx`, `mcp`) is installed automatically on first run.
19
+ ## Install (60 seconds)
17
20
 
18
- ### 1 — Add to your IDE's MCP config
21
+ **Requires Python 3.9+** on your PATH. Everything else (`networkx`, `mcp`) installs automatically on first run.
19
22
 
20
- Paste this JSON into your IDE's MCP config file (paths listed below):
23
+ Add this to your IDE's MCP config file:
21
24
 
22
25
  ```json
23
26
  {
@@ -30,103 +33,79 @@ Paste this JSON into your IDE's MCP config file (paths listed below):
30
33
  }
31
34
  ```
32
35
 
33
- #### Config file locations
36
+ **Where to find your config file:**
34
37
 
35
- | IDE | Config file |
38
+ | IDE | Config path |
36
39
  |-----|-------------|
37
- | **Antigravity** | `~/.gemini/antigravity/mcp/` (MCP server directory) |
38
- | **Cursor** | `~/.cursor/mcp.json` |
39
- | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
40
- | **Claude Code** | `~/.claude.json` (or run `claude mcp add`) |
41
- | **VS Code** | `.vscode/mcp.json` in your workspace root |
40
+ | Antigravity | `~/.gemini/config/mcp_config.json` |
41
+ | Cursor | `~/.cursor/mcp.json` |
42
+ | Windsurf | `~/.codeium/windsurf/mcp_config.json` |
43
+ | Claude Code | `~/.claude.json` |
44
+ | VS Code | `.vscode/mcp.json` |
42
45
 
43
- ### 2 — Use it
46
+ Restart your IDE. Done — no cloning, no Python setup beyond having it installed.
44
47
 
45
- Just talk to your IDE's AI normally:
48
+ ---
46
49
 
47
- ```
48
- You: "fix the file upload error handler"
49
- IDE: calls query_repo → gets [FileUploader.tsx, lib/upload.ts, …]
50
- IDE: reads only those 5 files instead of the whole repo
51
- ```
50
+ ## What it gives your agent
52
51
 
53
- ---
52
+ Three tools, automatically available once connected:
54
53
 
55
- ## Tools exposed
54
+ ### `query_repo`
55
+ *"Find the files relevant to this change."*
56
56
 
57
- ### `query_repo(repo_path, query, top_n?)`
57
+ Ranks every file in your repo against a natural-language query using filename matching, content matching, and graph proximity. Returns confidence-scored results with plain-English reasoning.
58
58
 
59
- Ranks the most relevant files for a change request.
59
+ ### `analyze_impact`
60
+ *"If I change this file, what breaks?"*
60
61
 
61
- **Parameters:**
62
- - `repo_path` — absolute path to the repository root
63
- - `query` — natural-language description of the change (e.g. `"change the download button color"`)
64
- - `top_n` — max results to return (default `5`, max `20`)
62
+ Walks the dependency graph upstream from any file to find every direct and transitive dependent. Flags likely test files so your agent knows what to re-run. Essential before touching shared files like `types/`, `utils/`, or config.
65
63
 
66
- **Returns:**
67
- ```json
68
- {
69
- "query": "change the download button",
70
- "repo": "/path/to/repo",
71
- "total_files_scanned": 142,
72
- "results": [
73
- {
74
- "rank": 1,
75
- "path": "components/DownloadButton.tsx",
76
- "score": 0.9800,
77
- "confidence": "high",
78
- "matched_terms": ["button", "download"],
79
- "reasoning": "Filename strongly matches query terms; file contents heavily reference query terms."
80
- }
81
- ]
82
- }
83
- ```
64
+ ### `scan_repo`
65
+ *"What files exist here?"*
84
66
 
85
- ### `scan_repo(repo_path)`
67
+ Lists every source file `contextl` can see — useful for the agent to orient itself before doing anything else.
86
68
 
87
- Lists all source files the engine can see in a repository. Useful for verifying coverage before querying.
69
+ ---
88
70
 
89
- **Returns:**
90
- ```json
91
- {
92
- "repo": "/path/to/repo",
93
- "total_files": 142,
94
- "files": [
95
- { "path": "components/Button.tsx", "extension": ".tsx", "size_bytes": 1024 }
96
- ]
97
- }
98
- ```
71
+ ## How the ranking works
72
+
73
+ 1. **Keyword match** — does the filename contain query terms?
74
+ 2. **Content match** — does the file's source code mention the terms?
75
+ 3. **Graph proximity** — files connected to high-scoring files get a relevance boost
76
+ 4. **Centrality (PageRank)** — heavily-connected files rank higher when scores tie
99
77
 
100
78
  ---
101
79
 
102
- ## How it works
80
+ ## Supported languages
103
81
 
104
- The engine runs **entirely locally** — no network calls, no AI APIs, no data leaves your machine.
82
+ TypeScript, TSX, JavaScript, JSX — built for Next.js and React codebases first.
105
83
 
106
- Scoring uses four signals:
84
+ Python, Go, and Rust support are on the roadmap.
107
85
 
108
- | Signal | Weight | Description |
109
- |--------|--------|-------------|
110
- | Keyword match | 0.5 | Query terms in the file path / name |
111
- | Content match | 0.5 | Query terms inside the file source |
112
- | Neighbor bonus | +0.15 | Files near high-scoring files in the import graph |
113
- | PageRank | 0.05 | Tiebreaker: more connected files rank slightly higher |
86
+ ---
114
87
 
115
- Supports **Next.js / React / TypeScript** repos (`.ts`, `.tsx`, `.js`, `.jsx`). Automatically detects `@/` path aliases from `tsconfig.json`.
88
+ ## Why this exists
89
+
90
+ AI coding agents are increasingly good at writing code. They're still bad at knowing *where* to look. On a 5,000-file repo, an agent might read 100+ files just to change a logo. `contextl` exists to fix that — and to eventually give agents a real model of your codebase's architecture, not just a file list.
116
91
 
117
92
  ---
118
93
 
119
- ## Requirements
94
+ ## Also available for Python
95
+
96
+ ```bash
97
+ pip install contextl-mcp
98
+ ```
120
99
 
121
- | Requirement | Version |
122
- |-------------|---------|
123
- | Node.js | ≥ 18 |
124
- | Python | ≥ 3.9 |
125
- | `networkx` | auto-installed |
126
- | `mcp` | auto-installed |
100
+ Same engine, same tools — installable via PyPI for Python-first workflows.
127
101
 
128
102
  ---
129
103
 
104
+ ## Links
105
+
106
+ - [GitHub](https://github.com/DS0710-coder/contextl)
107
+ - [PyPI package](https://pypi.org/project/contextl-mcp)
108
+
130
109
  ## License
131
110
 
132
111
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "contextl",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "description": "contextl — finds the most relevant files in your codebase for any change request. MCP server for AI coding agents.",
5
5
  "keywords": [
6
6
  "mcp",