inspect-mcp 0.1.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,252 @@
+# inspect-mcp
+
+An MCP server that gives AI coding agents instant, structured understanding of any codebase.
+
+One tool call. Full project context. No more fumbling.
+
+---
+
+## The problem
+
+AI coding agents (Claude Code, Cursor, Aider, Cline, Windsurf) waste significant time and tokens orienting themselves every session:
+
+```
+Agent: Let me look at package.json...          # tool call 1
+Agent: Now let me see the directory structure... # tool call 2
+Agent: Let me check tsconfig.json...            # tool call 3
+Agent: What's in the src/ folder?               # tool call 4
+Agent: How is the auth module structured?       # tool call 5
+```
+
+That's 5 tool calls, ~30 seconds, and hundreds of tokens burned before any real work begins. Multiply that across every task, every session, every day.
+
+## The solution
+
+```
+Agent: inspect scan /path/to/project   # 1 tool call, <3 seconds
+```
+
+Returns everything the agent needs in structured JSON:
+
+| What | Why it matters |
+|------|---------------|
+| **Project identity** | Language, framework, package manager, runtime — no guessing |
+| **Smart file tree** | Full structure with noise collapsed (node_modules, dist, .git) |
+| **Symbol index** | Every exported function, class, type with signatures and line numbers |
+| **Dependency map** | Who imports what — bidirectional, internal files only |
+| **Health baseline** | Existing linter/type errors so the agent knows what it inherited vs introduced |
+
+## Three commands
+
+### `scan` — understand the project
+
+First call does a full scan. Subsequent calls are incremental (only re-processes what git says changed). Cached and fast.
+
+```json
+{
+  "command": "scan",
+  "path": "/path/to/project",
+  "include_health": false
+}
+```
+
+### `changed` — what moved since last scan?
+
+After a `git pull`, branch switch, or teammate's push. Returns deltas, blast radius, and new/removed/modified symbols.
+
+```json
+{
+  "command": "changed",
+  "path": "/path/to/project"
+}
+```
+
+### `impact` — before I edit this, what depends on it?
+
+Point it at a file or symbol. Get direct dependents, transitive dependents, usage sites with line numbers, and test coverage status.
+
+```json
+{
+  "command": "impact",
+  "path": "/path/to/project",
+  "target": "src/lib/auth.ts:getUserById"
+}
+```
+
+## Why this matters
+
+### For developers using AI agents
+
+- **Fewer wasted tool calls** — 1 call replaces 3-5 exploratory ones
+- **Fewer broken edits** — the agent knows the dependency graph before touching anything
+- **Faster sessions** — orientation in seconds, not minutes
+- **Better context** — agents make smarter decisions with structured project knowledge
+
+### For agent framework builders
+
+- **Drop-in MCP tool** — standard protocol, works with any MCP client
+- **Structured JSON** — consistent, machine-parseable output with stable keys
+- **Incremental by design** — stays useful throughout a session, not just the first call
+
+### For teams with large codebases
+
+- **Scales to thousands of files** — tree-sitter parsing with smart collapsing
+- **Git-native** — handles pulls, rebases, branch switches correctly
+- **Zero config** — works out of the box for TypeScript, JavaScript, Python, Rust, Go, Java, Ruby
+- **Fully local** — no network calls, no cloud, no telemetry
+
+## Installation
+
+### Claude Code
+
+```bash
+claude mcp add inspect-mcp -- npx inspect-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "inspect-mcp": {
+      "command": "npx",
+      "args": ["inspect-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "inspect-mcp": {
+      "command": "npx",
+      "args": ["inspect-mcp"]
+    }
+  }
+}
+```
+
+### Global install
+
+```bash
+npm install -g inspect-mcp
+```
+
+### Build from source
+
+```bash
+git clone https://github.com/ykushch/inspecta.git
+cd inspecta
+pnpm install
+pnpm build
+node dist/index.js
+```
+
+When using a source build with MCP clients, replace `npx inspect-mcp` with `node /absolute/path/to/inspecta/dist/index.js`.
+
+## Agent instructions
+
+Add to your `CLAUDE.md` or agent system prompt:
+
+```markdown
+## Codebase awareness
+
+- At the start of any coding task, call `inspect scan` to understand the project
+- Before editing a function used elsewhere, call `inspect impact` to see dependents
+- After `git pull` or branch switch, call `inspect changed` to see what moved
+
+## Token efficiency
+
+Pair with [RTK](https://github.com/rtk-ai/rtk) to reduce token usage by 60-90% on
+CLI operations (git, test runners, linters). inspect-mcp gives structured codebase
+context in a single tool call; RTK compresses everything else.
+
+Install: `brew install rtk && rtk init --global`
+```
+
+## How it works
+
+- **Project detection** — reads config files (package.json, pyproject.toml, Cargo.toml, go.mod, etc.) to identify language, framework, package manager, and available tools
+- **File tree** — recursive walk with smart collapsing (node_modules → `{ _collapsed: true, file_count: 48210 }`)
+- **Symbols** — tree-sitter WASM parses source files to extract functions, classes, types with full signatures
+- **Dependencies** — tree-sitter extracts imports, resolves paths, builds a bidirectional adjacency map
+- **Health** — runs the project's own configured linters/type-checkers and structures the output
+- **Cache** — results cached in `.inspect/` anchored to git HEAD; incremental updates on subsequent calls
+
+## Performance targets
+
+| Operation | Target |
+|-----------|--------|
+| Initial scan (500 files) | < 3 seconds |
+| Impact query | < 500ms |
+| Incremental update | < 1 second |
+
+## Monorepo & workspace support
+
+inspecta automatically detects and handles multi-project layouts:
+
+- **Monorepos** — when the root has no config file, sub-projects are detected in child directories
+- **Workspace directories** — recurses into `packages/`, `libs/`, `apps/`, `modules/`, `services/`, etc.
+- **Python** — builds a package index from all `__init__.py` files, resolving absolute imports (`from mylib.config import settings`) regardless of nesting depth
+- **Java** — builds a fully-qualified class index from all `.java` files, resolving cross-module imports
+- **TypeScript/JS** — resolves relative imports and path aliases from `tsconfig.json`
+
+Works with any directory structure — no configuration needed.
+
+## Supported languages
+
+| Language | Project detection | Symbols | Dependencies |
+|----------|-------------------|---------|-------------|
+| TypeScript | Yes | Yes | Yes |
+| JavaScript | Yes | Yes | Yes |
+| Python | Yes | Yes | Yes |
+| Java | Yes | Yes | Yes |
+| Rust | Yes | No | No |
+| Go | Yes | No | No |
+| Ruby | Yes | No | No |
+| Kotlin | Build detection only | No | No |
+
+## Design principles
+
+1. **Speed over completeness** — fast partial answers beat slow perfect ones
+2. **Structured JSON only** — every response is machine-parseable, no prose
+3. **Local and private** — no network calls, no cloud, no telemetry
+4. **Git-native** — anchored to commits, not filesystem watchers
+5. **Incremental by default** — only re-process what changed
+6. **Zero config** — works out of the box, optional config for customization
+
+## Configuration
+
+Optional `inspect.config.json` in your project root:
+
+```json
+{
+  "collapse_dirs": ["node_modules", "dist", "build", ".next", "target"],
+  "ignore_patterns": ["*.min.js", "*.generated.*", "*.d.ts"],
+  "max_file_size_kb": 100,
+  "tree_depth": 6,
+  "health_timeout_ms": 15000
+}
+```
+
+## Maintainer release flow
+
+1. Update `version` in `package.json`.
+2. Merge the release commit and confirm CI is green.
+3. Create and push a matching tag such as `v0.1.1`.
+4. GitHub Actions verifies the tag, runs `pnpm lint`, `pnpm test`, `pnpm build`, packs the tarball, creates a GitHub Release, and publishes to npm.
+
+**Setup:**
+1. On npm: go to **Settings → "Trusted Publishing"** → link the `ykushch/inspecta` repository.
+2. On GitHub: add your npm automation token as the `NPM_TOKEN` secret in **Settings → Secrets → Actions**.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }