{"id":50360499,"url":"https://github.com/jagonzalr/knocoph","last_synced_at":"2026-05-30T01:06:02.128Z","repository":{"id":341220669,"uuid":"1169237314","full_name":"jagonzalr/knocoph","owner":"jagonzalr","description":"Knocoph (nok-of) is a local MCP server that parses TypeScript and JavaScript codebases into a persistent knowledge graph stored in SQLite.","archived":false,"fork":false,"pushed_at":"2026-04-25T11:38:31.000Z","size":563,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T12:25:23.702Z","etag":null,"topics":["code-analysis","javascript","knowledge-graph","mcp","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/knocoph","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jagonzalr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-28T11:32:56.000Z","updated_at":"2026-04-25T11:38:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jagonzalr/knocoph","commit_stats":null,"previous_names":["jagonzalr/knocoph"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/jagonzalr/knocoph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jagonzalr%2Fknocoph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jagonzalr%2Fknocoph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jagonzalr%2Fknocoph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jagonzalr%2Fknocoph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jagonzalr","download_url":"https://codeload.github.com/jagonzalr/knocoph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jagonzalr%2Fknocoph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33676206,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-analysis","javascript","knowledge-graph","mcp","typescript"],"created_at":"2026-05-30T01:06:01.509Z","updated_at":"2026-05-30T01:06:02.113Z","avatar_url":"https://github.com/jagonzalr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Knocoph\n\nKnocoph (nok-of) is a local [MCP](https://modelcontextprotocol.io/) server that transforms TypeScript and JavaScript codebases into a persistent code knowledge graph stored in SQLite.\n\nInstead of AI assistants greedily reading entire files and burning context tokens, Knocoph enables **structural codebase navigation** through deterministic graph queries. Navigate call chains, import graphs, inheritance hierarchies, and symbol dependencies with near-instant responses and minimal token consumption.\n\n## Installation\n\nInstall globally so the `knocoph` command is available in PATH:\n\n```bash\nnpm install -g knocoph\n```\n\n### Configuring the MCP server\n\nAdd Knocoph to your MCP client configuration (e.g. `.mcp.json`, `claude_desktop_config.json`):\n\n```json\n{\n  \"servers\": {\n    \"knocoph\": {\n      \"type\": \"stdio\",\n      \"command\": \"knocoph\",\n      \"env\": {\n        \"knocoph_DB\": \"./.knocoph/graph.db\",\n        \"knocoph_ROOT\": \".\"\n      }\n    }\n  }\n}\n```\n\nBoth `env` variables are **optional** — Knocoph uses sensible defaults if they are omitted:\n\n| Variable       | Default               | Description                                                                                                                     |\n| -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| `knocoph_DB`   | `./.knocoph/graph.db` | Path to the SQLite database file. Relative paths resolve from the working directory (the project root).                         |\n| `knocoph_ROOT` | `.`                   | Root directory to auto-index on first run (before any `index_project` call). Relative paths resolve from the working directory. |\n\nMinimal configuration with defaults (no `env` block required):\n\n```json\n{\n  \"servers\": {\n    \"knocoph\": {\n      \"type\": \"stdio\",\n      \"command\": \"knocoph\"\n    }\n  }\n}\n```\n\n### Instructing AI assistants to use Knocoph\n\nTo guide your AI assistant (Claude, Copilot, etc.) to use Knocoph MCP tools effectively instead of reading files directly, copy the instructions from [MCP_USAGE.md](MCP_USAGE.md) into your AI assistant's system prompt, AGENTS.md, CLAUDE.md or equivalent configuration file.\n\nThese instructions teach AI to:\n\n- Use `find_symbol` before opening files\n- Use graph queries to understand relationships instead of burning context tokens\n- Call `explain_impact` before making changes\n- Use `get_snippet` to fetch exact code ranges rather than entire files\n\nThis approach minimizes token consumption and provides fast, accurate structural answers.\n\n## Features\n\n- **Persistent code graph** — parses codebases into nodes (symbols) and edges (relationships), stored in SQLite\n- **Automatic indexing** — file watcher keeps the graph updated as code changes\n- **Zero file reading** — query structural questions without opening source files\n- **MCP tools** — 7 specialized query tools for different exploration patterns\n- **Cross-file relationships** — tracks imports, exports, calls, inheritance, and containment\n- **TypeScript path alias resolution** — automatically reads `tsconfig.json` to resolve `@scope/...` style imports\n\n## How It Works\n\n1. **Parse** — TypeScript ESLint parser extracts symbols, types, and relationships from source files\n2. **Graph** — Builds nodes for functions, classes, interfaces, variables, etc.\n3. **Store** — Persists all metadata and edges in SQLite\n4. **Query** — Serve structural answers via MCP tools without re-parsing\n\n## MCP Tools\n\n| Tool                 | Purpose                                                                          |\n| -------------------- | -------------------------------------------------------------------------------- |\n| `codebase_overview`  | Get structural summary of entire codebase (files, symbols, kind distribution)    |\n| `find_symbol`        | Locate any symbol by name; optionally include source code snippet                |\n| `get_neighbors`      | Explore incoming/outgoing relationships by symbol name or ID                     |\n| `get_snippet`        | Fetch exact source code snippet for a symbol or line range                       |\n| `explain_impact`     | Blast radius and dependency analysis; understand why a symbol exists             |\n| `query_architecture` | File-level view — what symbols does a file define and import/export?             |\n| `index_project`      | Trigger or refresh graph indexing; auto-detects `tsconfig.json` for path aliases |\n\n## TypeScript Path Aliases\n\nIf your project uses `compilerOptions.paths` in `tsconfig.json` (e.g. `@myapp/*`, `@auth`), Knocoph resolves them automatically. When `index_project` is called, it looks for `tsconfig.json` in the project root and reads `compilerOptions.paths` and `baseUrl` to resolve aliased imports to their real file paths.\n\nNo configuration needed for the standard setup:\n\n```jsonc\n// tsconfig.json\n{\n  \"compilerOptions\": {\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"@myapp/*\": [\"src/*\"], // @myapp/utils → src/utils.ts\n      \"@auth\": [\"src/auth/index.ts\"],\n    },\n  },\n}\n```\n\nIf your `tsconfig.json` is not at the project root, pass the path explicitly:\n\n```\nindex_project { root_dir: \".\", tsconfig_path: \"./packages/app/tsconfig.json\" }\n```\n\nSupported patterns: simple prefix wildcards (`@scope/*`) and exact matches (`@auth`). Only the first replacement in each array is used. Complex multi-wildcard patterns are skipped.\n\n## Quick Reference\n\n```bash\n# Install globally\nnpm install -g knocoph\n\n# Run tests (contributors)\nnpm run test:ci\n\n# Format and lint (contributors)\nnpm run prettier\nnpm run lint\n```\n\n## Design Principles\n\n- **Graph before files** — structural questions answered without file I/O\n- **Deterministic queries** — same input always returns same result\n- **Token efficiency** — small, precise responses instead of full file contents\n- **Simplicity** — explicit, readable code over clever abstractions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjagonzalr%2Fknocoph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjagonzalr%2Fknocoph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjagonzalr%2Fknocoph/lists"}