Gjalla MCP Server

A Model Context Protocol (MCP) server that provides comprehensive software development guidance and project architecture insights through AI coding agents.

Features

🎯 Unified Guidance Endpoint (New!)

A single get_guidance tool now powers every type of generalized help:

• Best Practices (intent=best_practices) – security, workflow, performance, user experience, etc.
• Production Readiness (intent=production_readiness) – implementation-focused checklist filtered by category or keywords.
• Production Checklist (intent=production_checklist) – summary/detailed pre-flight checks.
• Feature Design Guidance (intent=feature_design) – domain-specific architecture advice (web-app, payments, AI, etc.).

Provide optional category, keywords, or format fields to tailor results. The endpoint returns the same curated guidance previously spread across multiple tools.

✅ Production Readiness Checklist (Enhanced!)

Comprehensive checklist organized by implementation priority:

• Security Essentials - Must complete before any user access
• Infrastructure & Reliability - Required for stable operation
• Monitoring & Operations - Essential for maintaining production systems
• Development & Deployment - Important for ongoing development
• User Experience & Business - Features for user satisfaction

Each item includes:

• Detailed implementation steps
• Check points for verification
• Priority guidance (Critical, High, Medium, Conditional)

🏗️ Project Architecture Tools

• Architecture overview and consolidated architecture spec (contextType=architecture_spec).
• Element details (now include immediate parent + 2-hop knowledge graph neighborhood).
• Architecture decisions, principles, technology stack, and feature/capability definitions.

Setup

Generic Endpoints (No Project Required)

For best practices and production readiness guidance, you only need an API key:

# Required
export GJALLA_API_KEY="your-api-key-here"

# Optional
export GJALLA_BASE_URL="https://gjalla.io"  # defaults to gjalla.io

Project-Specific Endpoints

For architecture and project-specific data, also set:

export GJALLA_PROJECT_ID="your-project-id"

API Key Setup

1. Go to Gjalla Settings
2. Create a new API key
3. Important: Enable "Allow Generic Access" for best practices endpoints
4. Copy the API key (shown only once during creation)

Available Tools

Server Capabilities

• get_server_capabilities - Always available - Discover what tools and features are available

Generic Tools (No Project ID Required)

• get_guidance – Unified endpoint for best practices, production readiness, production checklist, and feature design guidance (requires intent; optional category, keywords, format).

Project-Specific Tools (Require Project ID)

• get_architecture_spec – Consolidated architecture spec including principles/decisions (contextType=architecture_spec).
• get_data_flows – Summaries of captured data flows/traces; provide traceId for a detailed sequence.
• get_architecture_element_details – Detailed element information (description, immediate parent, 2-hop knowledge graph neighborhood).
• get_architecture_decisions – Architecture decisions and rationale (filterable by status).
• get_architecture_principles – Project principles and guidelines.
• get_project_capabilities – Features and requirements (filterable by category/feature/status/search text).
• get_tech_stack_overview – Highlighted technology stack and external dependencies.

Usage Examples

Ask for Security Guidance

const guidance = await getGuidance({
  intent: "best_practices",
  category: "security-essentials",
  keywords: ["aws", "secrets"]
});

// Returns categorized practices with:
// - Common mistakes to avoid
// - Step-by-step implementation guidance
// - Code snippets and priority levels

Check Production Readiness

const readiness = await getGuidance({
  intent: "production_readiness",
  category: "infrastructure",
  keywords: ["monitoring"]
});

// Returns organized checklist with critical/high/medium priorities
// and concrete implementation steps.

Quick Pre-Deployment Check

const preflight = await getGuidance({
  intent: "production_checklist",
  format: "summary"
});

// Returns concise verification items (secrets, auth, logging, etc.).

Pull the Architecture Spec

const spec = await getArchitectureSpec({ projectId: 123 });
const element = await getArchitectureElementDetails({ projectId: 123, elementId: "api-server" });

// `spec` contains the element tree plus principles/decisions.
// `element` includes the element description, parent descriptive ID,
// connections, related decisions, and a 2-hop knowledge graph neighborhood.

Integration with AI Coding Agents

This MCP server is designed to provide AI coding agents with:

1. Practical Guidance - Real-world best practices based on production experience
2. Actionable Steps - Specific implementation instructions, not just theory
3. Priority Awareness - Understanding what's critical vs. nice-to-have
4. Code Examples - Concrete examples that can be adapted
5. Comprehensive Coverage - From security essentials to user experience

AI Agent Discovery

Start with get_server_capabilities - This tool tells the AI agent:

• What tools are available (generic vs. project-specific)
• Current configuration status (project ID set or not)
• Recommended workflow for development tasks
• Categories and options for each tool

Example AI workflow:

// 1. First, discover what's available
const capabilities = await getServerCapabilities();
// AI learns: "I have generic tools available, but no project-specific tools"

// 2. Use appropriate tools based on capabilities
if (capabilities.hasProjectId) {
  const spec = await getArchitectureSpec();
  const element = await getArchitectureElementDetails({ elementId: "api-server" });
} else {
  const guidance = await getGuidance({ intent: "best_practices", category: "security-essentials" });
}

Perfect for use with:

• Claude Desktop
• Custom AI coding assistants
• Development workflow automation
• Code review processes
• Pre-deployment verification

Categories and Priorities

Best Practices Categories

• Security Essentials (Critical) - Authentication, input validation, secret management
• Development Workflow (High) - Error handling, environment config, code organization
• Performance & Scalability (High) - Database optimization, caching, rate limiting
• Data Management (High) - Transactions, backups, data validation
• Monitoring & Observability (High) - Logging, health checks, alerting
• User Experience (Medium) - Loading states, mobile responsiveness

Production Readiness Priorities

• Critical - Non-negotiable for production (security, data protection)
• High - Complete before public launch (monitoring, infrastructure)
• Medium - Complete within first month (optimization, UX improvements)
• Conditional - Depends on business model (payments, advanced features)

Error Handling

The server provides helpful error messages:

• Missing API key → Instructions on creating one with generic access
• Missing project ID → Guidance on which endpoints are still available
• Invalid permissions → Clear instructions on updating API key settings

Migration Notes

• Legacy tools get_best_practices, get_production_readiness, get_production_checklist, and get_feature_design_guidance were consolidated into get_guidance. Pass an intent to keep the same workflows.
• MCP clients calling the removed tools should switch to get_guidance immediately; the old routes no longer exist on the MCP server or Agent API.

Contributing

This MCP server focuses on providing practical, actionable guidance based on real-world software development experience. When contributing:

1. Emphasize Practical Value - Include specific implementation steps
2. Provide Code Examples - Show concrete examples, not just concepts
3. Consider Real-World Pitfalls - Include common mistakes developers make
4. Prioritize by Impact - Focus on what actually matters in production

License

MIT License - see LICENSE file for details.

Troubleshooting

Common Issues

❌ "Forbidden" errors for get_guidance

• Problem: Your API key doesn't have allowGenericAccess permission
• Solution: Run npm run fix-api-key for detailed step-by-step instructions
• Quick fix: Create a new API key at https://gjalla.io/settings/api-keys with "Allow Generic Access" ✅ checked

❌ "Missing authorization header"

• Make sure you've set the GJALLA_API_KEY environment variable
• Verify your API key starts with gja_

❌ "Invalid token" or "API key not found"

• Check that your API key is correct and hasn't been deleted
• Ensure the API key hasn't expired
• Try creating a new API key with fresh permissions

❌ "Project not found" (for project-specific tools)

• Verify your GJALLA_PROJECT_ID is correct
• Make sure you have access to the project in Gjalla
• Check if the project exists and hasn't been deleted

❌ MCP tools not appearing in Cursor

• Restart Cursor completely after configuration changes
• Check the MCP server logs in Cursor's developer tools (Help → Toggle Developer Tools)
• Verify your .cursor/mcp_servers.json configuration is correct

API Key Diagnostics

Run this command for detailed troubleshooting help:

npm run fix-api-key

This utility will:

• Guide you through creating a properly configured API key
• Explain why the "Allow Generic Access" permission is needed
• Provide step-by-step Cursor configuration instructions
• Show you how to verify the fix worked

Testing Your Setup

# Test the MCP server locally
npm test

# Should show:
# ✅ Server capabilities
# ✅ Best practices (if API key has generic access)
# ✅ Production checklist

Security

• API keys are transmitted securely over HTTPS
• Keys are never logged or stored by the MCP server
• All communication uses gjalla's secure API endpoints which verify project access