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

Before marking a feature or fix complete, ensure your implementation aligns with best practices (get_guidance with intent=best_practices) and project rules (get_project_rules).

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.

Releasing

The MCP server is automatically published to npm when changes are merged to main.

To release a new version:

1. Update the version in packages/gjalla-mcp-server/package.json
2. Merge your PR to main
3. The workflow will automatically publish if the version doesn't exist on npm

If you don't update the version, the workflow will skip publishing. This lets you merge documentation or internal changes without triggering a release.

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