npm package: @gjalla/mcp-server
Description: Gjalla MCP Server - Provides architecture context to AI coding agents through Model Context Protocol
Author: Gjalla
Latest version: 1.1.8

# 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:

```bash
# 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:

```bash
export GJALLA_PROJECT_ID="your-project-id"
```

### API Key Setup
1. Go to [Gjalla Settings](https://gjalla.io/settings/api-keys)
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
```javascript
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
```javascript
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
```javascript
const preflight = await getGuidance({
  intent: "production_checklist",
  format: "summary"
});

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

### Pull the Architecture Spec
```javascript
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:
```javascript
// 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:

```bash
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

```bash
# 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