@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/mcp-gateway/README.md

@@ -1,14 +1,26 @@
-# Agent Kit MCP Gateway
+# Agent Kit MCP Gateway v2.0
 
-> Live Project Cortex - MCP Server providing real-time project context to AI agents.
+> Enterprise-grade MCP Server with OAuth 2.1, Streamable HTTP, and OpenTelemetry
+
+## 🚀 What's New in v2.0
+
+| Feature | Description |
+|---------|-------------|
+| **Streamable HTTP** | Modern transport for remote/production use |
+| **OAuth 2.1 + API Keys** | Enterprise security with scope-based access |
+| **OpenTelemetry** | Distributed tracing and metrics |
+| **New Tools** | `force_sync`, `get_metrics`, `get_server_info` |
 
 ## Features
 
 - **get_project_context** - Read AGENTS.md sections
+- **get_project_intelligence** - Code/Docs distribution analysis
 - **analyze_dependencies** - Query dependency graph
-- **search_code_logic** - Semantic code search
+- **search_knowledge** - Semantic code search
 - **get_impact_zone** - Impact analysis for changes
 - **force_sync** - Refresh all AI data
+- **get_metrics** - Server performance metrics
+- **get_server_info** - Server capabilities
 
 ## Installation
 
@@ -20,7 +32,32 @@ npm run build
 
 ## Usage
 
-### With Claude Desktop
+### Local Development (stdio)
+
+```bash
+npm run dev
+```
+
+### Production (HTTP)
+
+```bash
+MCP_ENABLE_HTTP=true MCP_HTTP_PORT=3100 npm run start:http
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PROJECT_ROOT` | Path to project root | Current directory |
+| `MCP_ENABLE_HTTP` | Enable HTTP transport | `false` |
+| `MCP_HTTP_PORT` | HTTP port | `3100` |
+| `MCP_ENABLE_AUTH` | Enable authentication | `false` |
+| `MCP_API_KEY` | Default API key | - |
+| `MCP_CORS_ORIGINS` | Comma-separated CORS origins | - |
+
+## Configuration
+
+### Claude Desktop (stdio)
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
@@ -38,7 +75,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-### With Cursor
+### Cursor (stdio)
 
 Add to `.cursor/mcp.json`:
 
@@ -56,22 +93,65 @@ Add to `.cursor/mcp.json`:
 }
 ```
 
-### Development
+### Remote Client (HTTP)
+
+```typescript
+// Connect to HTTP transport
+const client = new MCPClient({
+  transport: "http",
+  url: "http://localhost:3100/mcp",
+  auth: {
+    type: "api-key",
+    key: process.env.MCP_API_KEY,
+  }
+});
+```
+
+## Security
+
+### API Key Authentication
 
 ```bash
-# Run in dev mode
-npm run dev
+# Set API key
+export MCP_API_KEY="your-secret-key"
+export MCP_ENABLE_AUTH=true
 
-# Build for production
-npm run build
+# Client usage
+curl -X POST http://localhost:3100/mcp \
+  -H "X-API-Key: your-secret-key" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", ...}'
 ```
 
-## Environment Variables
+### Scopes
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PROJECT_ROOT` | Path to project root | Current directory |
-| `AGENT_KIT_PATH` | Path to Agent Kit installation | Auto-detected |
+| Scope | Tools Allowed |
+|-------|---------------|
+| `read:project` | get_project_context, get_project_intelligence |
+| `read:graph` | analyze_dependencies, get_impact_zone |
+| `read:search` | search_knowledge, search_code_logic |
+| `write:sync` | force_sync |
+| `admin:*` | All tools |
+
+## Observability
+
+### Metrics Endpoint
+
+```bash
+# Get server metrics
+curl http://localhost:3100/health
+
+# Via MCP tool
+mcp call get_metrics
+```
+
+### Trace Output
+
+Traces are automatically exported to configured OTLP endpoint:
+
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+```
 
 ## Tools Reference
 
@@ -88,12 +168,11 @@ npm run build
 ```json
 {
   "file_path": "src/components/Button.tsx",
-  "direction": "both", // "imports", "imported_by", "both"
-  "depth": 2
+  "direction": "both" // "imports", "imported_by", "both"
 }
 ```
 
-### search_code_logic
+### search_knowledge
 
 ```json
 {
@@ -107,8 +186,7 @@ npm run build
 
 ```json
 {
-  "file_path": "src/utils/auth.ts",
-  "depth": 3
+  "file_path": "src/utils/auth.ts"
 }
 ```
 
@@ -119,3 +197,74 @@ npm run build
   "target": "all" // or "graph", "rag", "agents_md"
 }
 ```
+
+### get_metrics
+
+```json
+{}
+```
+
+Returns:
+```json
+{
+  "tools": {
+    "search_knowledge": {
+      "calls": 150,
+      "avgDuration": 320,
+      "p95Duration": 890,
+      "errorRate": 0.02
+    }
+  },
+  "summary": {
+    "totalRequests": 195,
+    "avgDuration": 280,
+    "uptime": 86400
+  }
+}
+```
+
+### get_server_info
+
+```json
+{}
+```
+
+Returns server capabilities and version.
+
+## Architecture
+
+```
+mcp-gateway/
+├── src/
+│   ├── index.ts              # Main entry point
+│   ├── transports/
+│   │   ├── index.ts
+│   │   └── streamableHttp.ts # HTTP transport
+│   ├── auth/
+│   │   ├── index.ts
+│   │   ├── oauth.ts          # OAuth 2.1 implementation
+│   │   ├── scopes.ts         # Scope definitions
+│   │   └── middleware.ts     # Auth middleware
+│   ├── observability/
+│   │   ├── index.ts
+│   │   └── otel.ts           # OpenTelemetry integration
+│   └── sync/
+│       └── ...               # Auto-sync modules
+├── dist/                     # Compiled output
+├── package.json
+└── README.md
+```
+
+## Upgrading from v1.x
+
+1. Update dependencies: `npm install`
+2. Rebuild: `npm run build`
+3. (Optional) Enable new features via env vars
+
+No breaking changes to tool interfaces.
+
+---
+
+**Version:** 2.0.0  
+**MCP SDK:** 1.12.0  
+**Node.js:** ≥20.0.0

package/.agent/mcp-gateway/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@musashishao/agent-kit-mcp",
-    "version": "1.0.0",
-    "description": "MCP Gateway Server for Agent Kit - Live Project Cortex",
+    "version": "2.0.0",
+    "description": "MCP Gateway Server for Agent Kit - Enterprise-grade with OAuth 2.1, Streamable HTTP, and OpenTelemetry",
     "type": "module",
     "main": "dist/index.js",
     "bin": {
@@ -10,19 +10,34 @@
     "scripts": {
         "build": "tsc",
         "dev": "tsx src/index.ts",
+        "dev:http": "MCP_ENABLE_HTTP=true tsx src/index.ts",
         "start": "node dist/index.js",
-        "watch": "tsc --watch"
+        "start:http": "MCP_ENABLE_HTTP=true node dist/index.js",
+        "watch": "tsc --watch",
+        "test": "node --test dist/**/*.test.js"
     },
     "dependencies": {
-        "@modelcontextprotocol/sdk": "^1.0.0",
+        "@modelcontextprotocol/sdk": "^1.12.0",
         "zod": "^3.23.0"
     },
     "devDependencies": {
-        "@types/node": "^20.0.0",
+        "@types/node": "^22.0.0",
         "tsx": "^4.0.0",
-        "typescript": "^5.0.0"
+        "typescript": "^5.5.0"
     },
     "engines": {
-        "node": ">=18.0.0"
+        "node": ">=20.0.0"
+    },
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "ai-agent",
+        "anthropic",
+        "claude",
+        "opentelemetry"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/ngotanthieu2000/agent-kit"
     }
 }

package/.agent/mcp-gateway/src/auth/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Auth module exports
+ */
+
+// Re-export from oauth (excluding conflicting middleware exports)
+export {
+    generatePKCE,
+    verifyPKCE,
+    generateAccessToken,
+    validateAccessToken,
+    revokeAccessToken,
+    generateAuthorizationCode,
+    exchangeAuthorizationCode,
+    hasScope,
+    hasAllScopes,
+    hasAnyScope,
+    extractBearerToken,
+    createApiKey,
+    validateApiKey,
+    extractApiKey,
+    MCP_SCOPES,
+    type OAuthConfig,
+    type TokenPayload,
+    type AuthResult,
+    type PKCEChallenge,
+    type MCPScope,
+} from "./oauth.js";
+
+// Re-export from scopes
+export {
+    TOOL_SCOPES,
+    DEFAULT_SCOPES,
+    READ_ALL_SCOPES,
+    AGENT_SCOPES,
+    FULL_ACCESS_SCOPES,
+    getRequiredScopes,
+    hasToolAccess,
+    getScopeDescription,
+    isValidScope,
+    parseScopes,
+    serializeScopes,
+    getScopesForTools,
+    validateScopeRequest,
+} from "./scopes.js";
+
+// Re-export from middleware (with unique names)
+export {
+    createAuthMiddleware,
+    authorizeToolCall,
+    requireToolAuth,
+    requireScopes,
+    type AuthMiddlewareConfig,
+    type AuthenticatedRequest,
+} from "./middleware.js";
+

package/.agent/mcp-gateway/src/auth/middleware.ts

@@ -0,0 +1,242 @@
+/**
+ * Authentication Middleware for MCP Gateway
+ * 
+ * Combines OAuth 2.1 and API Key authentication
+ * with flexible configuration.
+ */
+
+import type { IncomingMessage, ServerResponse } from "http";
+import { validateAccessToken, extractBearerToken, validateApiKey, extractApiKey, type AuthResult, type MCPScope } from "./oauth.js";
+import { hasToolAccess, getRequiredScopes } from "./scopes.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface AuthMiddlewareConfig {
+    /** Enable authentication (default: true) */
+    enabled?: boolean;
+    /** Allow API key authentication */
+    allowApiKey?: boolean;
+    /** Allow bearer token authentication */
+    allowBearer?: boolean;
+    /** Paths that don't require authentication */
+    publicPaths?: string[];
+    /** Custom authentication handler */
+    customAuth?: (req: IncomingMessage) => Promise<AuthResult | null>;
+}
+
+export interface AuthenticatedRequest extends IncomingMessage {
+    auth?: AuthResult;
+}
+
+// ============================================================================
+// Middleware Factory
+// ============================================================================
+
+/**
+ * Create authentication middleware
+ */
+export function createAuthMiddleware(config: AuthMiddlewareConfig = {}) {
+    const {
+        enabled = true,
+        allowApiKey = true,
+        allowBearer = true,
+        publicPaths = ["/health", "/metrics"],
+        customAuth,
+    } = config;
+
+    return async function authMiddleware(
+        req: AuthenticatedRequest,
+        res: ServerResponse,
+        next: () => void
+    ): Promise<void> {
+        // Skip if auth disabled
+        if (!enabled) {
+            next();
+            return;
+        }
+
+        // Skip public paths
+        if (publicPaths.some(path => req.url?.startsWith(path))) {
+            next();
+            return;
+        }
+
+        let authResult: AuthResult | null = null;
+
+        // Try custom auth first
+        if (customAuth) {
+            authResult = await customAuth(req);
+        }
+
+        // Try Bearer token
+        if (!authResult && allowBearer) {
+            const token = extractBearerToken(req);
+            if (token) {
+                authResult = validateAccessToken(token);
+            }
+        }
+
+        // Try API key
+        if (!authResult && allowApiKey) {
+            const apiKey = extractApiKey(req);
+            if (apiKey) {
+                authResult = validateApiKey(apiKey);
+            }
+        }
+
+        // No credentials provided
+        if (!authResult) {
+            res.writeHead(401, {
+                "Content-Type": "application/json",
+                "WWW-Authenticate": 'Bearer realm="MCP Server", API-Key realm="MCP Server"',
+            });
+            res.end(JSON.stringify({
+                error: "authentication_required",
+                message: "Valid authentication credentials required",
+            }));
+            return;
+        }
+
+        // Invalid credentials
+        if (!authResult.valid) {
+            res.writeHead(401, {
+                "Content-Type": "application/json",
+                "WWW-Authenticate": `Bearer realm="MCP Server", error="${authResult.error}"`,
+            });
+            res.end(JSON.stringify({
+                error: "invalid_token",
+                message: authResult.error,
+            }));
+            return;
+        }
+
+        // Attach auth to request
+        req.auth = authResult;
+        next();
+    };
+}
+
+// ============================================================================
+// Tool Authorization
+// ============================================================================
+
+/**
+ * Check if request is authorized for a specific tool
+ */
+export function authorizeToolCall(
+    req: AuthenticatedRequest,
+    toolName: string
+): { authorized: boolean; error?: string } {
+    const auth = req.auth;
+
+    if (!auth || !auth.valid) {
+        return { authorized: false, error: "Not authenticated" };
+    }
+
+    if (!auth.scopes) {
+        return { authorized: false, error: "No scopes granted" };
+    }
+
+    if (!hasToolAccess(auth.scopes, toolName)) {
+        const required = getRequiredScopes(toolName);
+        return {
+            authorized: false,
+            error: `Insufficient scope. Required: ${required.join(", ")}`,
+        };
+    }
+
+    return { authorized: true };
+}
+
+/**
+ * Middleware to enforce scope for a specific tool
+ */
+export function requireToolAuth(toolName: string) {
+    return function toolAuthMiddleware(
+        req: AuthenticatedRequest,
+        res: ServerResponse,
+        next: () => void
+    ): void {
+        const result = authorizeToolCall(req, toolName);
+
+        if (!result.authorized) {
+            res.writeHead(403, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: "insufficient_scope",
+                message: result.error,
+                tool: toolName,
+                required_scopes: getRequiredScopes(toolName),
+            }));
+            return;
+        }
+
+        next();
+    };
+}
+
+/**
+ * Middleware to enforce specific scopes
+ */
+export function requireScopes(...requiredScopes: MCPScope[]) {
+    return function scopeMiddleware(
+        req: AuthenticatedRequest,
+        res: ServerResponse,
+        next: () => void
+    ): void {
+        const auth = req.auth;
+
+        if (!auth || !auth.valid || !auth.scopes) {
+            res.writeHead(403, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: "insufficient_scope",
+                message: "Authentication required with appropriate scopes",
+                required_scopes: requiredScopes,
+            }));
+            return;
+        }
+
+        const missing = requiredScopes.filter(scope => {
+            // Admin wildcard
+            if (auth.scopes!.includes("admin:*")) return false;
+
+            // Direct match
+            if (auth.scopes!.includes(scope)) return false;
+
+            // Category wildcard
+            const [category] = scope.split(":");
+            if (auth.scopes!.includes(`${category}:*`)) return false;
+
+            return true;
+        });
+
+        if (missing.length > 0) {
+            res.writeHead(403, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: "insufficient_scope",
+                message: "Missing required scopes",
+                required_scopes: requiredScopes,
+                missing_scopes: missing,
+                granted_scopes: auth.scopes,
+            }));
+            return;
+        }
+
+        next();
+    };
+}
+
+// ============================================================================
+// Utility Exports
+// ============================================================================
+
+export { AuthResult, MCPScope } from "./oauth.js";
+export { hasToolAccess, getRequiredScopes, TOOL_SCOPES, DEFAULT_SCOPES, AGENT_SCOPES } from "./scopes.js";
+
+export default {
+    createAuthMiddleware,
+    authorizeToolCall,
+    requireToolAuth,
+    requireScopes,
+};