# Gjalla MCP Server - Query Examples

> Examples of queries AI coding agents can make to Gjalla's Model Context Protocol (MCP) server

## Available MCP Tools

### Discovery Tools

#### `get_accessible_projects`
Get list of projects available to this API key.

**Query:**
```json
{
  "tool": "get_accessible_projects"
}
```

**Response:**
```json
{
  "projects": [
    {
      "projectId": 123,
      "name": "E-commerce Platform",
      "repoUrl": "github.com/acme/platform",
      "lastAnalyzed": "2025-01-18T10:30:00Z"
    }
  ]
}
```

---

### Architecture Queries

#### `get_architecture_spec`
Get consolidated architecture overview for a project.

**Query:**
```json
{
  "tool": "get_architecture_spec",
  "projectId": 123
}
```

**Response:**
```json
{
  "containers": [
    {
      "elementId": "web-app",
      "name": "Web Application",
      "type": "container",
      "description": "React SPA serving customer-facing UI",
      "technology": "React 18, TypeScript, Vite"
    },
    {
      "elementId": "api-gateway",
      "name": "API Gateway",
      "type": "container",
      "description": "Express REST API handling authentication, routing",
      "technology": "Node.js, Express, PostgreSQL"
    }
  ],
  "relationships": [
    {
      "from": "web-app",
      "to": "api-gateway",
      "type": "calls",
      "protocol": "HTTPS/REST"
    }
  ],
  "principles": [
    {
      "id": "principle-1",
      "name": "API-First Design",
      "description": "All features exposed via REST API before UI implementation"
    }
  ],
  "decisions": [
    {
      "id": "adr-003",
      "title": "Use PostgreSQL for Primary Database",
      "status": "accepted",
      "decision": "PostgreSQL chosen for ACID guarantees and JSON support"
    }
  ]
}
```

---

#### `get_source_of_truth_doc`
Fetch canonical docs, codebase context, or must-maintain docs.

**Query:**
```json
{
  "tool": "get_source_of_truth_doc",
  "projectId": 123,
  "type": "architecture"
}
```

**Response:**
```json
{
  "contextType": "architecture",
  "metadata": {
    "source": "analysis_artifact",
    "format": "text"
  },
  "content": "# Architecture Overview\n..."
}
```

---

#### `get_project_capabilities`
Query what your system can actually do, with code-level proof.

**Query:**
```json
{
  "tool": "get_project_capabilities",
  "projectId": 123,
  "category": "user_management"
}
```

**Response:**
```json
{
  "capabilities": [
    {
      "capability_id": "cap-user-registration",
      "capability_name": "User Registration",
      "category": "user_management",
      "feature": "authentication",
      "status": "active",
      "acceptance_criteria": [
        "Email validation required",
        "Password minimum 8 characters",
        "Email confirmation sent on signup"
      ],
      "evidence": {
        "implementation_files": [
          "server/services/UserService.ts",
          "server/api/auth/signup.ts"
        ],
        "test_files": [
          "server/tests/services/UserService.test.ts"
        ]
      }
    }
  ]
}
```

---

#### `get_project_rules`
Get decisions, principles, and invariants that constrain implementation.

**Query:**
```json
{
  "tool": "get_project_rules",
  "projectId": 123,
  "type": "adr",
  "status": "active"
}
```

**Response:**
```json
{
  "rules": [
    {
      "id": "adr-005",
      "ruleType": "adr",
      "name": "No Direct Database Access from API Layer",
      "description": "All database operations must go through the storage layer",
      "status": "accepted",
      "rationale": "Maintain separation of concerns and enable easier testing",
      "applicableFilePatterns": ["server/api/**/*.ts"]
    }
  ]
}
```

---

### Knowledge Graph Queries

#### `get_impact_for_node`
Understand what depends on a file before modifying it.

**Query:**
```json
{
  "tool": "get_impact_for_node",
  "projectId": 123,
  "filePath": "server/services/EmailService.ts"
}
```

**Response:**
```json
{
  "node": {
    "gid": "kg-node-456",
    "name": "EmailService",
    "nodeType": "c4_code",
    "codePath": "server/services/EmailService.ts"
  },
  "dependents": {
    "nodes": [
      {
        "gid": "kg-node-789",
        "name": "UserRegistrationHandler",
        "nodeType": "c4_code",
        "codePath": "server/api/auth/signup.ts"
      },
      {
        "gid": "kg-node-790",
        "name": "PasswordResetService",
        "nodeType": "c4_code",
        "codePath": "server/services/PasswordResetService.ts"
      }
    ],
    "stats": {
      "nodeCount": 8,
      "truncated": false
    }
  },
  "dependencies": {
    "nodes": [
      {
        "gid": "kg-node-234",
        "name": "nodemailer",
        "nodeType": "third_party_package"
      }
    ]
  }
}
```

---

#### `get_dependencies_for_node`
What does this file depend on?

**Query:**
```json
{
  "tool": "get_dependencies_for_node",
  "projectId": 123,
  "filePath": "server/services/UserService.ts",
  "depth": 1
}
```

**Response:**
```json
{
  "node": {
    "gid": "kg-node-123",
    "name": "UserService",
    "codePath": "server/services/UserService.ts"
  },
  "dependencies": {
    "nodes": [
      {
        "gid": "kg-node-124",
        "name": "UserStorage",
        "codePath": "server/storage/UserStorage.ts"
      },
      {
        "gid": "kg-node-125",
        "name": "EmailService",
        "codePath": "server/services/EmailService.ts"
      },
      {
        "gid": "kg-node-126",
        "name": "bcrypt",
        "nodeType": "third_party_package"
      }
    ]
  }
}
```

---

### Guidance Queries

#### `get_guidance`
Get best practices, production checklists, and feature design guidance.

**Query:**
```json
{
  "tool": "get_guidance",
  "intent": "best_practices",
  "keywords": ["authentication", "security"]
}
```

**Response:**
```json
{
  "intent": "best_practices",
  "practices": [
    {
      "title": "Secure Password Storage",
      "description": "Always hash passwords with bcrypt or Argon2, never store plaintext",
      "category": "security",
      "applicability": "Any system handling user credentials"
    },
    {
      "title": "Session Token Rotation",
      "description": "Rotate session tokens on privilege escalation or sensitive operations",
      "category": "authentication",
      "applicability": "Session-based authentication systems"
    }
  ]
}
```

---

## Common Agent Workflows

### Before Implementing a Feature
1. `get_project_capabilities` - Check if capability already exists
2. `get_project_rules` - Understand constraints (decisions, principles)
3. `get_architecture_spec` - Understand where new code should fit

### Before Modifying a File
1. `get_impact_for_node` - See what depends on this file (blast radius)
2. `get_dependencies_for_node` - Understand what this file needs
3. `get_project_rules` - Check for applicable rules/invariants

### After Implementation
1. Gjalla automatically analyzes commits and PRs
2. GitHub check shows architecture impact
3. Change receipts track system evolution

---

## Integration

### Claude Desktop / Cursor
Add to MCP settings:
```json
{
  "mcpServers": {
    "gjalla": {
      "command": "npx",
      "args": ["-y", "@gjalla/mcp-server"],
      "env": {
        "GJALLA_API_KEY": "your-api-key",
        "GJALLA_PROJECT_ID": "123"
      }
    }
  }
}
```

### API Access
All MCP tools are also available via REST API:
```
POST https://gjalla.io/api/agent/v1/{tool}
Authorization: Bearer {api-key}
```