Query Interface Specification

{
  "version": "1.0.0",
  "generated_at": "2024-12-18T15:30:00Z",
  "project": { ... },
  "stats": { ... },
  "files": { "<path>": { ... } },
  "symbols": { "<qualified_name>": { ... } },
  "graph": { "forward": { ... }, "reverse": { ... } },
  "domains": { "<name>": { ... } },
  "constraints": { "by_file": { ... }, "by_lock_level": { ... } }
}

jq '.files | keys' .acp.cache.json

[
  "src/auth/session.ts",
  "src/auth/jwt.ts",
  "src/utils/helpers.ts"
]

jq '.files["src/auth/session.ts"]' .acp.cache.json

{
  "path": "src/auth/session.ts",
  "module": "Session Service",
  "summary": "User session management",
  "lines": 245,
  "language": "typescript",
  "domains": ["authentication"],
  "layer": "service",
  "stability": "stable"
}

jq '.symbols["src/auth/session.ts:SessionService.validateSession"]' .acp.cache.json

{
  "name": "validateSession",
  "qualified_name": "src/auth/session.ts:SessionService.validateSession",
  "type": "method",
  "file": "src/auth/session.ts",
  "lines": [45, 89],
  "signature": "(token: string) => Promise<Session | null>",
  "summary": "Validates JWT and returns session",
  "exported": true,
  "async": true
}

jq '.constraints.by_file["src/auth/session.ts"].lock_level' .acp.cache.json

"restricted"

jq '.constraints.by_lock_level.frozen[]' .acp.cache.json

"src/config/production.ts"
"src/security/keys.ts"

jq '.constraints.by_lock_level.restricted' .acp.cache.json

[
  "src/auth/session.ts",
  "src/billing/payment.ts"
]

jq '.constraints.by_file["src/auth/session.ts"]' .acp.cache.json

{
  "lock_level": "restricted",
  "lock_reason": "Security critical",
  "style": "google-typescript",
  "quality": ["security-review"]
}

jq '.domains | keys' .acp.cache.json

["authentication", "billing", "database", "api"]

jq '.domains["authentication"]' .acp.cache.json

{
  "name": "authentication",
  "description": "User authentication and session management",
  "files": ["src/auth/session.ts", "src/auth/jwt.ts"],
  "symbols": [
    "src/auth/session.ts:SessionService.validateSession",
    "src/auth/jwt.ts:verifyToken"
  ]
}

jq '.domains["authentication"].files[]' .acp.cache.json

"src/auth/session.ts"
"src/auth/jwt.ts"

jq '.graph.forward["src/auth/session.ts:SessionService.validateSession"]' .acp.cache.json

[
  "src/auth/jwt.ts:verifyToken",
  "src/db/sessions.ts:findSession"
]

jq '.graph.reverse["src/auth/jwt.ts:verifyToken"]' .acp.cache.json

[
  "src/auth/session.ts:SessionService.validateSession",
  "src/api/middleware.ts:authMiddleware"
]

jq '.symbols | to_entries | map(select(.key | contains("validate"))) | .[].key' .acp.cache.json

"src/auth/session.ts:SessionService.validateSession"
"src/utils/validation.ts:validateEmail"

jq '.files | to_entries | map(select(.value.language == "typescript")) | .[].key' .acp.cache.json

jq '.symbols | to_entries | map(select(.value.async == true)) | .[].key' .acp.cache.json

jq '.symbols | to_entries | map(select(.value.exported == true)) | .[].value.name' .acp.cache.json

jq '.files | to_entries | map(select(.value.layer == "service")) | .[].key' .acp.cache.json

jq '.stats' .acp.cache.json

{
  "files": 127,
  "symbols": 523,
  "lines": 15420,
  "annotation_coverage": 45.2
}

jq '.symbols | to_entries | group_by(.value.type) | map({type: .[0].value.type, count: length})' .acp.cache.json

[
  {"type": "function", "count": 234},
  {"type": "method", "count": 189},
  {"type": "class", "count": 67},
  {"type": "const", "count": 33}
]

jq '.files | to_entries | group_by(.value.language) | map({language: .[0].value.language, count: length})' .acp.cache.json

jq --arg sym "src/auth/session.ts:SessionService.validateSession" '
  .graph.forward[$sym] as $callees |
  [$callees[] | . as $c | {callee: $c, calls: .graph.forward[$c]}]
' .acp.cache.json

jq '
  .domains["authentication"].files as $auth_files |
  .constraints.by_file | to_entries |
  map(select(.key | IN($auth_files[]))) |
  map(select(.value.lock_level == "normal" or .value.lock_level == null)) |
  .[].key
' .acp.cache.json

jq '{
  project: .project.name,
  files: .stats.files,
  symbols: .stats.symbols,
  domains: (.domains | keys),
  frozen_count: (.constraints.by_lock_level.frozen | length),
  restricted_count: (.constraints.by_lock_level.restricted | length)
}' .acp.cache.json

acp query symbol <name>

acp query symbol validateSession

{
  "name": "validateSession",
  "qualified_name": "src/auth/session.ts:SessionService.validateSession",
  "type": "method",
  "file": "src/auth/session.ts",
  "lines": [45, 89],
  "signature": "(token: string) => Promise<Session | null>",
  "summary": "Validates JWT and returns session"
}

acp query file <path>

acp query file src/auth/session.ts

acp query callers <symbol>

acp query callers "src/auth/jwt.ts:verifyToken"

src/auth/session.ts:SessionService.validateSession
src/api/middleware.ts:authMiddleware

acp query callees <symbol>

acp query callees "src/auth/session.ts:SessionService.validateSession"

src/auth/jwt.ts:verifyToken
src/db/sessions.ts:findSession

acp query domains

authentication: 5 files, 23 symbols
billing: 8 files, 45 symbols
database: 12 files, 67 symbols
api: 15 files, 89 symbols

acp query domain <name>

acp query domain authentication

acp query stats

Files: 127
Symbols: 523
Lines: 15420
Coverage: 45.2%
Domains: 4
Layers: 6

acp constraints <path>

acp constraints src/auth/session.ts

File: src/auth/session.ts
Lock Level: restricted
Lock Reason: Security critical
Style: google-typescript
Quality Requirements:
  - security-review
 
⚠ This file requires approval before modification.

acp constraints src/auth/session.ts --json

{
  "file": "src/auth/session.ts",
  "lock_level": "restricted",
  "lock_reason": "Security critical",
  "style": "google-typescript",
  "quality": ["security-review"],
  "can_modify": false,
  "approval_needed": true
}

acp query '.domains | keys'
acp query '.constraints.by_lock_level.frozen'

// Get symbol details
acp_query({ type: "symbol", name: "validateSession" })
 
// Get domain info
acp_query({ type: "domain", name: "authentication" })
 
// Find callers
acp_query({ type: "callers", name: "src/auth/jwt.ts:verifyToken" })
 
// Search for symbols
acp_query({ type: "search", pattern: "validate" })
 
// Get stats
acp_query({ type: "stats" })

{
  "file": "src/auth/session.ts",
  "lock_level": "restricted",
  "lock_reason": "Security critical",
  "style": "google-typescript",
  "behavior": "conservative",
  "quality": ["security-review"],
  "can_modify": {
    "allowed": true,
    "approval_needed": true,
    "requirements": ["Explain changes before making them"]
  }
}

acp_expand({ 
  text: "Check $SYM_VALIDATE_SESSION for the bug",
  mode: "summary"
})

{
  "original": "Check $SYM_VALIDATE_SESSION for the bug",
  "expanded": "Check validateSession (src/auth/session.ts:45-89) - Validates JWT tokens for the bug",
  "variables_found": ["SYM_VALIDATE_SESSION"],
  "variables_resolved": ["SYM_VALIDATE_SESSION"],
  "variables_unresolved": []
}

{
  "mcpServers": {
    "acp": {
      "command": "acp-mcp-server",
      "args": ["--dir", "/path/to/your/project"]
    }
  }
}

{
  "mcpServers": {
    "acp": {
      "command": "node",
      "args": ["/path/to/acp-mcp-server/dist/index.js", "--dir", "/path/to/project"]
    }
  }
}

import { readFileSync } from 'fs';
 
// Load cache
const cache = JSON.parse(readFileSync('.acp.cache.json', 'utf-8'));
 
// Query symbol
function getSymbol(name: string) {
  return Object.values(cache.symbols).find(s => s.name === name);
}
 
// Get callers
function getCallers(qualifiedName: string): string[] {
  return cache.graph.reverse[qualifiedName] || [];
}
 
// Check constraints
function canModify(filePath: string): { allowed: boolean; reason?: string } {
  const constraints = cache.constraints.by_file[filePath];
  if (!constraints) return { allowed: true };
  
  if (constraints.lock_level === 'frozen') {
    return { allowed: false, reason: constraints.lock_reason };
  }
  return { allowed: true };
}
 
// Get domain files
function getDomainFiles(domain: string): string[] {
  return cache.domains[domain]?.files || [];
}

import json
 
# Load cache
with open('.acp.cache.json') as f:
    cache = json.load(f)
 
# Query symbol
def get_symbol(name: str):
    for sym in cache['symbols'].values():
        if sym['name'] == name:
            return sym
    return None
 
# Get callers
def get_callers(qualified_name: str) -> list:
    return cache['graph']['reverse'].get(qualified_name, [])
 
# Check constraints
def can_modify(file_path: str) -> tuple[bool, str | None]:
    constraints = cache['constraints']['by_file'].get(file_path)
    if not constraints:
        return True, None
    
    if constraints.get('lock_level') == 'frozen':
        return False, constraints.get('lock_reason')
    return True, None
 
# Get domain files
def get_domain_files(domain: str) -> list:
    return cache['domains'].get(domain, {}).get('files', [])

use serde::{Deserialize, Serialize};
use std::collections::HashMap;
 
#[derive(Deserialize)]
struct Cache {
    files: HashMap<String, FileEntry>,
    symbols: HashMap<String, SymbolEntry>,
    graph: CallGraph,
    domains: HashMap<String, DomainEntry>,
    constraints: ConstraintIndex,
}
 
impl Cache {
    fn get_symbol(&self, name: &str) -> Option<&SymbolEntry> {
        self.symbols.values().find(|s| s.name == name)
    }
    
    fn get_callers(&self, qualified_name: &str) -> Vec<&str> {
        self.graph.reverse
            .get(qualified_name)
            .map(|v| v.iter().map(|s| s.as_str()).collect())
            .unwrap_or_default()
    }
    
    fn can_modify(&self, file_path: &str) -> (bool, Option<&str>) {
        match self.constraints.by_file.get(file_path) {
            Some(c) if c.lock_level == Some("frozen".into()) => {
                (false, c.lock_reason.as_deref())
            }
            _ => (true, None)
        }
    }
}

1. RECEIVE task from user
2. QUERY relevant context:
   - acp_query(type="domain", name=<relevant_domain>)
   - acp_query(type="search", pattern=<keywords>)
3. CHECK constraints before any modification:
   - acp_constraints(file=<target_file>)
4. RESPECT constraint response:
   - If frozen: refuse modification
   - If restricted: explain changes, request approval
   - If tests-required: include tests
5. PROCEED with task respecting constraints

# Start with a symbol
acp query symbol validateSession
 
# Find what it calls
acp query callees "src/auth/session.ts:SessionService.validateSession"
 
# Find what calls it
acp query callers "src/auth/session.ts:SessionService.validateSession"
 
# Explore the domain
acp query domain authentication

# Find all frozen files
jq '.constraints.by_lock_level.frozen' .acp.cache.json
 
# Find restricted files without lock reasons
jq '.constraints.by_file | to_entries | map(select(.value.lock_level == "restricted" and .value.lock_reason == null)) | .[].key' .acp.cache.json
 
# Find files in auth domain without constraints
jq --argjson auth_files '["src/auth/session.ts", "src/auth/jwt.ts"]' '
  .constraints.by_file | keys as $constrained |
  $auth_files | map(select(. as $f | $constrained | index($f) | not))
' .acp.cache.json

# Find all callers (direct)
jq '.graph.reverse["src/auth/jwt.ts:verifyToken"]' .acp.cache.json
 
# Find all callers (2 levels)
jq '
  .graph.reverse["src/auth/jwt.ts:verifyToken"] as $direct |
  $direct + [$direct[] as $d | .graph.reverse[$d][]] | unique
' .acp.cache.json