vecgrep 0.1.0__tar.gz

vecgrep-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies (with dev extras)
+        run: uv sync --extra dev
+
+      - name: Cache sentence-transformers model
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/huggingface
+            ~/.cache/torch
+          key: ${{ runner.os }}-st-model-all-MiniLM-L6-v2
+
+      - name: Check imports & server loads
+        run: |
+          uv run python -c "
+          from vecgrep.server import mcp
+          tools = [t.name for t in mcp._tool_manager.list_tools()]
+          assert 'index_codebase' in tools
+          assert 'search_code' in tools
+          assert 'get_index_status' in tools
+          print('All tools registered:', tools)
+          "
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short --cov=src/vecgrep --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+      - name: Type check (non-blocking)
+        run: uv run pyright src/ || true

vecgrep-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+htmlcov/
+.coverage
+*.cover
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Distribution
+*.whl
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store

vecgrep-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

vecgrep-0.1.0/CODEOWNERS

@@ -0,0 +1,2 @@
+# Global owner — reviews required on all PRs
+* @iamvirul

vecgrep-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in VecGrep a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainers directly. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

vecgrep-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to VecGrep
+
+Thanks for your interest in contributing!
+
+## Getting Started
+
+```bash
+git clone https://github.com/iamvirul/vecgrep
+cd vecgrep
+uv sync
+```
+
+## Development
+
+Run the server locally:
+```bash
+uv run vecgrep
+```
+
+Test against a codebase:
+```bash
+uv run python -c "
+from vecgrep.server import _do_index, search_code
+print(_do_index('/path/to/project'))
+print(search_code('your query here', '/path/to/project'))
+"
+```
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Make your changes
+4. Open a pull request against `main`
+
+## Guidelines
+
+- Keep PRs focused — one feature or fix per PR
+- Add tests for new functionality where practical
+- Follow existing code style (ruff for formatting/linting)
+- All `unsafe` usage (if any) must have a comment explaining why
+
+## Reporting Bugs
+
+Open a GitHub issue with steps to reproduce and your Python/OS version.

vecgrep-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iamvirul
+
+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.

vecgrep-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: vecgrep
+Version: 0.1.0
+Summary: Cursor-style vector search MCP plugin for Claude Code
+Project-URL: Homepage, https://github.com/iamvirul/VecGrep
+Project-URL: Repository, https://github.com/iamvirul/VecGrep
+Project-URL: Issues, https://github.com/iamvirul/VecGrep/issues
+Author: iamvirul
+License: MIT
+License-File: LICENSE
+Keywords: claude,code-search,embeddings,mcp,semantic-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: mcp[cli]<2.0,>=1.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: sentence-transformers<4.0,>=3.0
+Requires-Dist: tree-sitter-languages<2.0,>=1.10
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.360; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# VecGrep
+
+[![CI](https://github.com/iamvirul/VecGrep/actions/workflows/ci.yml/badge.svg)](https://github.com/iamvirul/VecGrep/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/iamvirul/VecGrep/branch/main/graph/badge.svg)](https://codecov.io/gh/iamvirul/VecGrep)
+
+Cursor-style semantic code search as an MCP plugin for Claude Code.
+
+Instead of grepping 50 files and sending 30,000 tokens to Claude, VecGrep returns the top 8 semantically relevant code chunks (~1,600 tokens). That's a **~95% token reduction** for codebase queries.
+
+## How it works
+
+1. **Chunk** — Parses source files with tree-sitter to extract semantic units (functions, classes, methods)
+2. **Embed** — Encodes each chunk locally using `all-MiniLM-L6-v2` (384-dim, ~80MB one-time download)
+3. **Store** — Saves embeddings + metadata in SQLite under `~/.vecgrep/<project_hash>/`
+4. **Search** — Cosine similarity over all embeddings returns the most relevant snippets
+
+Incremental re-indexing via SHA256 file hashing skips unchanged files.
+
+## Installation
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+pip install vecgrep        # standard pip
+uv tool install vecgrep   # uv tool (isolated, recommended)
+```
+
+## Claude Code integration
+
+Add to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json` or via `claude mcp add`):
+
+```json
+{
+  "mcpServers": {
+    "vecgrep": {
+      "command": "uvx",
+      "args": ["vecgrep"]
+    }
+  }
+}
+```
+
+Or with the CLI:
+
+```bash
+claude mcp add vecgrep -- uvx vecgrep
+```
+
+`uvx` downloads and runs VecGrep in an isolated environment on first use — no cloning or manual setup required.
+
+## Tools
+
+### `index_codebase(path, force=False)`
+
+Index a project directory. Skips unchanged files on subsequent calls.
+
+```
+index_codebase("/path/to/myproject")
+# → "Indexed 142 file(s), 1847 chunk(s) added (0 file(s) skipped, unchanged)"
+```
+
+### `search_code(query, path, top_k=8)`
+
+Semantic search. Auto-indexes if no index exists.
+
+```
+search_code("how does user authentication work", "/path/to/myproject")
+```
+
+Returns formatted snippets with file paths, line numbers, and similarity scores:
+
+```
+[1] src/auth.py:45-72 (score: 0.87)
+def authenticate_user(token: str) -> User:
+    ...
+
+[2] src/middleware.py:12-28 (score: 0.81)
+...
+```
+
+### `get_index_status(path)`
+
+Check index statistics.
+
+```
+Index status for: /path/to/myproject
+  Files indexed:  142
+  Total chunks:   1847
+  Last indexed:   2026-02-22T07:20:31+00:00
+  Index size:     28.4 MB
+```
+
+## Supported languages
+
+Python, JavaScript/TypeScript, Rust, Go, Java, C/C++, Ruby, Swift, Kotlin, C#
+
+All other text files fall back to sliding-window line chunks.
+
+## Index location
+
+`~/.vecgrep/<sha256-of-project-path>/index.db`
+
+Each project gets its own isolated index. Delete the directory to wipe the index.

vecgrep-0.1.0/README.md

@@ -0,0 +1,103 @@
+# VecGrep
+
+[![CI](https://github.com/iamvirul/VecGrep/actions/workflows/ci.yml/badge.svg)](https://github.com/iamvirul/VecGrep/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/iamvirul/VecGrep/branch/main/graph/badge.svg)](https://codecov.io/gh/iamvirul/VecGrep)
+
+Cursor-style semantic code search as an MCP plugin for Claude Code.
+
+Instead of grepping 50 files and sending 30,000 tokens to Claude, VecGrep returns the top 8 semantically relevant code chunks (~1,600 tokens). That's a **~95% token reduction** for codebase queries.
+
+## How it works
+
+1. **Chunk** — Parses source files with tree-sitter to extract semantic units (functions, classes, methods)
+2. **Embed** — Encodes each chunk locally using `all-MiniLM-L6-v2` (384-dim, ~80MB one-time download)
+3. **Store** — Saves embeddings + metadata in SQLite under `~/.vecgrep/<project_hash>/`
+4. **Search** — Cosine similarity over all embeddings returns the most relevant snippets
+
+Incremental re-indexing via SHA256 file hashing skips unchanged files.
+
+## Installation
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+pip install vecgrep        # standard pip
+uv tool install vecgrep   # uv tool (isolated, recommended)
+```
+
+## Claude Code integration
+
+Add to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json` or via `claude mcp add`):
+
+```json
+{
+  "mcpServers": {
+    "vecgrep": {
+      "command": "uvx",
+      "args": ["vecgrep"]
+    }
+  }
+}
+```
+
+Or with the CLI:
+
+```bash
+claude mcp add vecgrep -- uvx vecgrep
+```
+
+`uvx` downloads and runs VecGrep in an isolated environment on first use — no cloning or manual setup required.
+
+## Tools
+
+### `index_codebase(path, force=False)`
+
+Index a project directory. Skips unchanged files on subsequent calls.
+
+```
+index_codebase("/path/to/myproject")
+# → "Indexed 142 file(s), 1847 chunk(s) added (0 file(s) skipped, unchanged)"
+```
+
+### `search_code(query, path, top_k=8)`
+
+Semantic search. Auto-indexes if no index exists.
+
+```
+search_code("how does user authentication work", "/path/to/myproject")
+```
+
+Returns formatted snippets with file paths, line numbers, and similarity scores:
+
+```
+[1] src/auth.py:45-72 (score: 0.87)
+def authenticate_user(token: str) -> User:
+    ...
+
+[2] src/middleware.py:12-28 (score: 0.81)
+...
+```
+
+### `get_index_status(path)`
+
+Check index statistics.
+
+```
+Index status for: /path/to/myproject
+  Files indexed:  142
+  Total chunks:   1847
+  Last indexed:   2026-02-22T07:20:31+00:00
+  Index size:     28.4 MB
+```
+
+## Supported languages
+
+Python, JavaScript/TypeScript, Rust, Go, Java, C/C++, Ruby, Swift, Kotlin, C#
+
+All other text files fall back to sliding-window line chunks.
+
+## Index location
+
+`~/.vecgrep/<sha256-of-project-path>/index.db`
+
+Each project gets its own isolated index. Delete the directory to wipe the index.

vecgrep-0.1.0/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| latest  | yes       |
+
+## Reporting a Vulnerability
+
+Please **do not** report security vulnerabilities through public GitHub issues.
+
+Instead, open a [GitHub Security Advisory](https://github.com/iamvirul/vecgrep/security/advisories/new) or email the maintainer directly.
+
+Include as much detail as possible:
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+You can expect a response within 48 hours. If the issue is confirmed, a patch will be released as quickly as possible.

vecgrep-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "vecgrep"
+version = "0.1.0"
+description = "Cursor-style vector search MCP plugin for Claude Code"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "iamvirul" }]
+keywords = ["mcp", "semantic-search", "embeddings", "claude", "code-search"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "mcp[cli]>=1.0,<2.0",
+    "sentence-transformers>=3.0,<4.0",
+    "tree-sitter-languages>=1.10,<2.0",
+    "numpy>=1.26",
+]
+
+[project.urls]
+Homepage = "https://github.com/iamvirul/VecGrep"
+Repository = "https://github.com/iamvirul/VecGrep"
+Issues = "https://github.com/iamvirul/VecGrep/issues"
+
+[project.scripts]
+vecgrep = "vecgrep.server:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.4.0",
+    "pyright>=1.1.360",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vecgrep"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]
+
+[tool.pyright]
+pythonVersion = "3.12"
+include = ["src"]
+typeCheckingMode = "basic"

vecgrep-0.1.0/src/vecgrep/__init__.py

@@ -0,0 +1,3 @@
+"""VecGrep: Cursor-style vector search MCP plugin for Claude Code."""
+
+__version__ = "0.1.0"