project-graph-mcp 2.1.3 → 2.1.5

package/GUIDE.md

@@ -0,0 +1,237 @@
+# Project Graph MCP — Usage Guide
+
+## Quick Start Workflow
+1. `get_ai_context({ path: "src/" })` → boot AI context (skeleton + docs)
+2. `get_focus_zone({ recentFiles: ["src/parser.js"] })` → enriched context for area of interest
+3. Make code changes
+4. `invalidate_cache()` → always after edits
+5. `analyze({ action: "analysis_summary", path: "src/" })` → verify quality
+
+## Two-Tier Context Model
+Project Graph MCP operates on a dual-layer context model designed for token efficiency and high context awareness:
+- **Skeleton (Overview)**: Provides a high-level map of the whole project (2-5K tokens). It includes file paths, exported symbols, and structural relationships without the implementation details.
+- **Focus Zone (Detailed)**: When drilling into specific areas, agents receive the full context for those files (1-3K tokens per file), including implementation and associated `.ctx` documentation.
+
+The key insight: agents read the whole project cheaply via the skeleton, then drill into specific files with full context when needed.
+
+## Navigation
+Use the `navigate` tool to explore the codebase structure and dependencies.
+
+```javascript
+// Expand a specific symbol to see its definition
+navigate({ action: "expand", symbol: "MyClass" });
+
+// Find where a specific file or symbol is imported/used
+navigate({ action: "usages", path: "src/parser.js" });
+
+// Get dependencies of a specific file
+navigate({ action: "deps", path: "src/core/workspace.js" });
+
+// Trace the call chain for a function
+navigate({ action: "call_chain", symbol: "processData" });
+
+// List sub-projects or modules
+navigate({ action: "sub_projects" });
+```
+
+## Analysis
+Use the `analyze` tool to inspect code quality, find issues, and gather metrics.
+
+```javascript
+// Get a comprehensive summary of codebase health
+analyze({ action: "analysis_summary", path: "src/" });
+
+// Find dead or unused code
+analyze({ action: "dead_code", path: "src/" });
+
+// Detect potentially duplicate or similar functions
+analyze({ action: "similar_functions", path: "src/" });
+
+// Identify complex files requiring refactoring
+analyze({ action: "complexity", path: "src/" });
+
+// Find unusually large files
+analyze({ action: "large_files", path: "src/" });
+
+// Check for outdated framework patterns
+analyze({ action: "outdated_patterns", path: "src/" });
+
+// Find undocumented code blocks
+analyze({ action: "undocumented", path: "src/" });
+
+// Run a full suite of analysis checks
+analyze({ action: "full_analysis", path: "src/" });
+```
+
+## Compact Code
+Use the `compact` tool to compress and expand codebase files, enforce compact mode standards, and configure how code is presented to the AI.
+
+### Compact Mode Standards
+Compact mode enforces 5 style rules for maximum token efficiency:
+- **`missing-ctx-header`**: Every `.js` file must start with `// @ctx .context/path/to/file.ctx`
+- **`missing-ctx-file`**: Every `.js` file must have a corresponding `.ctx` documentation file
+- **`multi-line-imports`**: All imports must be on a single line
+- **`indented-lines`**: No indentation — all code must be flat (terser-minified)
+- **`long-names`**: All identifiers (const/let/var/function) must be ≤2 chars — `.ctx` provides readability
+- **`incomplete-ctx`**: Every export must be documented in `.ctx`, no `{DESCRIBE}` placeholders allowed
+
+### .pgignore
+File exclusions are configured via `.pgignore` (created automatically if missing):
+```
+# Third-party vendored code
+vendor/
+
+# Generated files
+.context/
+.expanded/
+```
+
+### Bidirectional Workflow
+The compact pipeline works in both directions:
+1. **Compact (fix:true)**: Parses readable code → generates `.ctx` with full signatures → minifies with terser
+2. **Expand**: Reads `.ctx` → restores JSDoc, readable names, and formatting
+
+```javascript
+// Validate compact mode compliance (read-only check)
+compact({ action: "validate_pipeline", path: "." });
+
+// Auto-fix all style violations + generate .ctx documentation
+compact({ action: "validate_pipeline", path: ".", fix: true });
+
+// Compact a single file
+compact({ action: "compact_file", path: "src/parser.js" });
+
+// Apply a targeted edit to a compacted file
+compact({ action: "edit", path: "src/parser.js", symbol: "parseFile", code: "..." });
+
+// Compact all files in a directory
+compact({ action: "compact_all", path: "src/" });
+
+// Format and beautify a file
+compact({ action: "beautify", path: "src/index.js" });
+
+// Expand a previously compacted file to its full content
+compact({ action: "expand_file", path: "src/parser.js" });
+
+// Expand the entire project back to full source
+compact({ action: "expand_project" });
+
+// Get current compaction mode settings
+compact({ action: "get_mode" });
+
+// Set compaction mode: 1 (compact, recommended) or 2 (full)
+compact({ action: "set_mode", mode: 1 });
+```
+
+## Documentation (.ctx)
+Use the `docs` tool to manage and interact with project context (`.ctx`) files.
+
+```javascript
+// Get documentation for a specific file
+docs({ action: "get", path: "src/core/workspace.js" });
+
+// Generate missing documentation for a directory
+docs({ action: "generate", path: "src/utils/" });
+
+// Check for stale or outdated documentation
+docs({ action: "check_stale", path: "src/" });
+
+// Validate interface and API contracts
+docs({ action: "validate_contracts", path: "src/" });
+```
+
+## Database Analysis
+Use the `db` tool to analyze database schemas and queries within the code.
+
+```javascript
+// Extract the inferred database schema
+db({ action: "schema", path: "src/" });
+
+// Find where specific database tables are accessed
+db({ action: "table_usage", table: "users" });
+
+// Identify defined tables that are never queried
+db({ action: "dead_tables", path: "src/" });
+```
+
+## Testing
+Use the `testing` tool to manage and track test states and annotations.
+
+```javascript
+// List tests marked as pending or TODO
+testing({ action: "pending", path: "tests/" });
+
+// Mark specific tests as passing
+testing({ action: "pass", testIds: ["test-123"] });
+
+// Mark specific tests as failing
+testing({ action: "fail", testIds: ["test-456"] });
+
+// Get a summary of current test statuses
+testing({ action: "summary", path: "tests/" });
+
+// Reset all test statuses
+testing({ action: "reset" });
+```
+
+## JSDoc
+Use the `jsdoc` tool to manage JSDoc comments and type annotations.
+
+```javascript
+// Check for inconsistencies between JSDoc and actual code
+jsdoc({ action: "check_consistency", path: "src/" });
+
+// Validate JSDoc types
+jsdoc({ action: "check_types", path: "src/" });
+
+// Generate missing JSDoc comments
+jsdoc({ action: "generate", path: "src/core/" });
+```
+
+## Filters
+Use the `filters` tool to configure which files the MCP server includes or ignores.
+
+```javascript
+// Get current active filters
+filters({ action: "get" });
+
+// Set specific inclusion/exclusion patterns
+filters({ action: "set", includes: ["src/**/*.js"], excludes: ["tests/"] });
+
+// Add patterns to the exclusion list
+filters({ action: "add_excludes", patterns: ["dist/", "build/"] });
+
+// Remove patterns from the exclusion list
+filters({ action: "remove_excludes", patterns: ["tests/"] });
+
+// Reset filters to default
+filters({ action: "reset" });
+```
+
+## Custom Rules
+Manage custom linting or architectural rules specific to the project.
+
+```javascript
+// Retrieve all custom rules
+get_custom_rules();
+
+// Define a new custom rule
+set_custom_rule({ name: "no-console", description: "Disallow console.log", pattern: "console\\.log" });
+
+// Check codebase against defined custom rules
+check_custom_rules({ path: "src/" });
+```
+
+## Self-Discovery Tools
+Agents can use these tools to learn about the workspace and available workflows.
+
+```javascript
+// Read a specific section of this usage guide
+get_usage_guide({ topic: "navigation" });
+
+// Retrieve project-specific coding guidelines and agent rules
+get_agent_instructions();
+
+// Fetch framework or library documentation referenced in the project
+get_framework_reference({ path: "src/" });
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-graph-mcp",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "type": "module",
   "description": "MCP server for AI agents — project graph, code quality analysis, visual web explorer. JS, TS, Python, Go.",
   "main": "src/network/server.js",
@@ -13,6 +13,7 @@
     "vendor/",
     "rules/",
     "docs/",
+    "GUIDE.md",
     "CONFIGURATION.md",
     "README.md",
     "LICENSE"

package/src/network/web-server.js

@@ -1,6 +1,6 @@
 // @ctx .context/src/network/web-server.ctx
 import e from"node:http";import t from"node:fs";import o from"node:path";import n from"node:crypto";import{fileURLToPath as a}from"node:url";import{WebSocketServer as s}from"ws";import{createServer as i}from"../mcp/mcp-server.js";import c from"../core/event-bus.js";import{registerService as r}from"./local-gateway.js";import{expandFile as l}from"../compact/expand.js";import{setRoots as _setRoots}from"../core/workspace.js";
-const d=o.dirname(a(import.meta.url)),p=o.join(d,"..",".."),m=o.join(p,"web"),h={"symbiote-node":o.join(p,"node_modules","symbiote-node"),symbiote:o.join(p,"node_modules","@symbiotejs","symbiote")},f={".html":"text/html",".js":"text/javascript",".mjs":"text/javascript",".css":"text/css",".json":"application/json",".svg":"image/svg+xml",".png":"image/png",".ico":"image/x-icon",".woff2":"font/woff2"};
+const d=o.dirname(a(import.meta.url)),p=o.join(d,"..","..");function _rv(k,n){const a=o.join(p,"node_modules",n||k);if(t.existsSync(a))return a;const b=o.join(p,"..","..","node_modules",n||k);if(t.existsSync(b))return b;const c=o.join(p,"..",n||k);return t.existsSync(c)?c:a}const m=o.join(p,"web"),h={"symbiote-node":_rv("symbiote-node"),symbiote:_rv("symbiote",o.join("@symbiotejs","symbiote"))},f={".html":"text/html",".js":"text/javascript",".mjs":"text/javascript",".css":"text/css",".json":"application/json",".svg":"image/svg+xml",".png":"image/png",".ico":"image/x-icon",".woff2":"font/woff2"};
 function g(e,n){const a=o.normalize(e).replace(/^(\.\.[/\\])+/,""),s=a.match(/^[/\\]?vendor[/\\]([^/\\]+)[/\\]?(.*)/);let i,c;if(s&&h[s[1]]?(c=h[s[1]],i=o.join(c,s[2]||"index.js")):(c=m,i=o.join(m,"/"===a?"index.html":a)),!i.startsWith(c))return n.writeHead(403),void n.end("Forbidden");if(t.existsSync(i)&&t.statSync(i).isDirectory()&&(i=o.join(i,"index.html")),!t.existsSync(i))return n.writeHead(404),void n.end("Not Found");const r=o.extname(i),l=f[r]||"application/octet-stream",d=t.readFileSync(i);n.writeHead(200,{"Content-Type":l,"Cache-Control":"no-cache, no-store, must-revalidate"}),n.end(d)}
 function u(e){return n.createHash("sha1").update(e+"258EAFA5-E914-47DA-95CA-5AB5ADF35C70").digest("base64")}
 function y(e){const t=Buffer.from(e,"utf8"),o=t.length;let n;return o<126?(n=Buffer.alloc(2),n[0]=129,n[1]=o):o<65536?(n=Buffer.alloc(4),n[0]=129,n[1]=126,n.writeUInt16BE(o,2)):(n=Buffer.alloc(10),n[0]=129,n[1]=127,n.writeBigUInt64BE(BigInt(o),2)),Buffer.concat([n,t])}