@majkapp/plugin-kit 3.2.1 → 3.3.1

package/docs/mcp-execution-api.md

@@ -0,0 +1,490 @@
+# MCP Execution API
+
+The MCP Execution API provides context-aware operations for interacting with MCP servers from your plugin. You can operate as an admin (system-level secrets) or as a specific teammate (user-scoped secrets).
+
+## Quick Start
+
+```typescript
+import { definePlugin } from '@majkapp/plugin-kit';
+
+export default definePlugin('my-plugin')
+  .withApi(async (ctx) => {
+    const { majk } = ctx;
+
+    // Single server operations
+    const server = await majk.mcpServers.get('server-id');
+
+    // Admin context - uses system secrets
+    const adminTools = await server.asAdmin().discoverTools();
+    const result = await server.asAdmin().executeTool('tool-name', { param: 'value' });
+
+    // Teammate context - uses teammate-specific secrets
+    const teammateTools = await server.asTeammate('teammate-id').discoverTools();
+    const result2 = await server.asTeammate('teammate-id').executeTool('tool-name', {});
+
+    // Everywhere - operate across all servers
+    const allTools = await majk.mcpServers.everywhere().asAdmin().discoverTools();
+    const anyResult = await majk.mcpServers.everywhere()
+      .asTeammate('tm-id')
+      .executeTool('any-tool', {});
+  });
+```
+
+## API Reference
+
+### MCPServerHandle
+
+Extended with context-aware methods:
+
+#### `.asAdmin(): MCPServerScopedHandle`
+
+Creates an admin-scoped handle that uses system-level secrets.
+
+```typescript
+const server = await ctx.majk.mcpServers.get('openai-server');
+const adminScope = server.asAdmin();
+
+// All operations use system secrets
+const tools = await adminScope.discoverTools();
+const result = await adminScope.executeTool('gpt-4-call', {
+  prompt: 'Hello world'
+});
+```
+
+#### `.asTeammate(teammateId: string): MCPServerScopedHandle`
+
+Creates a teammate-scoped handle that uses teammate-specific secrets.
+
+```typescript
+const server = await ctx.majk.mcpServers.get('openai-server');
+const teammateScope = server.asTeammate('teammate-123');
+
+// All operations use teammate's secrets
+const tools = await teammateScope.discoverTools();
+const result = await teammateScope.executeTool('gpt-4-call', {
+  prompt: 'Hello from teammate'
+});
+```
+
+### MCPServerScopedHandle
+
+Context-aware operations on a single server:
+
+#### `.discoverTools(): Promise<DiscoveredTool[]>`
+
+Discovers available tools from the MCP server.
+
+```typescript
+const tools = await server.asAdmin().discoverTools();
+console.log(`Found ${tools.length} tools`);
+
+tools.forEach(tool => {
+  console.log(`- ${tool.name}: ${tool.description}`);
+});
+```
+
+**Returns:**
+```typescript
+interface DiscoveredTool {
+  id: string;              // Tool identifier
+  name: string;            // Tool name
+  description: string;     // Tool description
+  inputSchema?: any;       // JSON schema for inputs
+  serverId: string;        // Server ID
+  serverName: string;      // Server name
+}
+```
+
+#### `.executeTool(toolName: string, params: Record<string, any>): Promise<any>`
+
+Executes a specific tool on the MCP server.
+
+```typescript
+const result = await server.asTeammate('tm-123').executeTool('gpt-4-call', {
+  prompt: 'Translate to Spanish: Hello world',
+  temperature: 0.7
+});
+
+console.log(result.content);
+```
+
+#### `.listResources(): Promise<any[]>`
+
+Lists available MCP resources.
+
+```typescript
+const resources = await server.asAdmin().listResources();
+console.log('Available resources:', resources);
+```
+
+#### `.listPrompts(): Promise<any[]>`
+
+Lists available MCP prompts.
+
+```typescript
+const prompts = await server.asAdmin().listPrompts();
+console.log('Available prompts:', prompts);
+```
+
+#### `.getServerInfo(): object`
+
+Gets information about the server and context.
+
+```typescript
+const info = server.asTeammate('tm-123').getServerInfo();
+console.log(info);
+// {
+//   id: 'server-id',
+//   name: 'OpenAI Server',
+//   type: 'local',
+//   context: 'teammate'
+// }
+```
+
+#### `.connect(): Promise<void>`
+
+Manually establishes a connection (lazy by default).
+
+```typescript
+await server.asAdmin().connect();
+```
+
+#### `.disconnect(): Promise<void>`
+
+Manually closes the connection.
+
+```typescript
+await server.asAdmin().disconnect();
+```
+
+### MCPServerAPI
+
+Extended with everywhere scope:
+
+#### `.everywhere(): EverywhereScope`
+
+Creates a scope for operating across all MCP servers.
+
+```typescript
+const everywhere = ctx.majk.mcpServers.everywhere();
+
+// Then scope to admin or teammate
+const adminScope = everywhere.asAdmin();
+const teammateScope = everywhere.asTeammate('tm-123');
+```
+
+### EverywhereScope
+
+Choose execution context:
+
+#### `.asAdmin(): EverywhereScopedHandle`
+
+Operate as admin across all servers.
+
+```typescript
+const scope = ctx.majk.mcpServers.everywhere().asAdmin();
+```
+
+#### `.asTeammate(teammateId: string): EverywhereScopedHandle`
+
+Operate as teammate across all servers.
+
+```typescript
+const scope = ctx.majk.mcpServers.everywhere().asTeammate('tm-123');
+```
+
+### EverywhereScopedHandle
+
+Aggregate operations across all servers:
+
+#### `.discoverTools(): Promise<DiscoveredTool[]>`
+
+Discovers tools from all MCP servers in parallel.
+
+```typescript
+const allTools = await ctx.majk.mcpServers
+  .everywhere()
+  .asAdmin()
+  .discoverTools();
+
+console.log(`Found ${allTools.length} tools across all servers`);
+
+// Group by server
+const byServer = {};
+allTools.forEach(tool => {
+  byServer[tool.serverName] = byServer[tool.serverName] || [];
+  byServer[tool.serverName].push(tool);
+});
+```
+
+**Note:** Uses `Promise.allSettled` - some servers can fail without affecting others.
+
+#### `.executeTool(toolName: string, params: Record<string, any>): Promise<any>`
+
+Automatically finds the server that provides a tool and executes it.
+
+```typescript
+// No need to know which server has the tool
+const result = await ctx.majk.mcpServers
+  .everywhere()
+  .asTeammate('tm-123')
+  .executeTool('any-tool-name', { param: 'value' });
+```
+
+**How it works:**
+1. Queries the tool repository to find which server provides the tool
+2. Creates a connection to that server with the appropriate context
+3. Executes the tool
+4. Returns the result
+
+#### `.listKnownTools(): Promise<any[]>`
+
+Lists all tools from the tool repository (not live discovery).
+
+```typescript
+const knownTools = await ctx.majk.mcpServers
+  .everywhere()
+  .asAdmin()
+  .listKnownTools();
+```
+
+#### `.getContextInfo(): object`
+
+Gets information about the execution context.
+
+```typescript
+const info = ctx.majk.mcpServers
+  .everywhere()
+  .asTeammate('tm-123')
+  .getContextInfo();
+
+console.log(info);
+// {
+//   type: 'teammate',
+//   id: 'tm-123',
+//   metadata: { context: 'teammate', teammateId: 'tm-123', scope: 'user' }
+// }
+```
+
+## Secret Management
+
+The execution system supports transparent secret resolution using `${secret:name}` syntax in MCP server configurations.
+
+### Creating Servers with Secrets
+
+```typescript
+await ctx.majk.mcpServers.create({
+  name: 'OpenAI Server',
+  type: 'local',
+  connectionConfig: {
+    command: 'node',
+    args: ['mcp-server.js'],
+    env: {
+      // Each teammate will use their own API key
+      OPENAI_API_KEY: '${secret:openai_api_key}',
+
+      // Explicit global scope
+      GLOBAL_TOKEN: '${secret:global/api_token}',
+
+      // Environment variable
+      PATH: '${env:PATH}'
+    }
+  }
+});
+```
+
+### Secret Scopes
+
+- `${secret:name}` - Uses context scope (global for admin, teammate for teammate)
+- `${secret:global/name}` - Explicit global scope
+- `${secret:teammate/name}` - Explicit teammate scope
+- `${secret:project/name}` - Explicit project scope
+- `${env:VAR}` - Environment variable
+
+### How It Works
+
+1. When you call `.asAdmin()` or `.asTeammate(id)`, a context is created
+2. The context determines which secrets to resolve
+3. On connection, `${secret:*}` references are replaced with actual values
+4. Each context gets its own connection with its own resolved secrets
+5. Admin contexts use system/global secrets
+6. Teammate contexts use teammate-specific secrets
+
+## Event Monitoring
+
+All MCP operations emit events that you can subscribe to:
+
+```typescript
+// Subscribe to MCP server events
+ctx.majk.eventBus.mcpServers().onUpdated(async (server) => {
+  // Check for tool discovery events
+  if (server.metadata?.type === 'tool_discovery_completed') {
+    console.log(`Discovered ${server.metadata.toolCount} tools`);
+  }
+
+  // Check for tool execution events
+  if (server.metadata?.type === 'tool_execution_completed') {
+    console.log(`Executed ${server.metadata.toolName} in ${server.metadata.duration}ms`);
+  }
+});
+```
+
+### Event Types
+
+Discovery events:
+- `tool_discovery_started`
+- `tool_discovery_completed`
+- `tool_discovery_failed`
+
+Execution events:
+- `tool_execution_started`
+- `tool_execution_completed`
+- `tool_execution_failed`
+
+Connection events:
+- `connection_established`
+- `connection_closed`
+- `secrets_resolved`
+
+Everywhere events:
+- `everywhere_discovery_started`
+- `everywhere_discovery_completed`
+- `everywhere_discovery_failed`
+- `everywhere_execution_started`
+- `everywhere_execution_completed`
+- `everywhere_execution_failed`
+
+## Common Patterns
+
+### Tool Discovery Dashboard
+
+```typescript
+export default definePlugin('tool-dashboard')
+  .withApi(async (ctx) => {
+    // Discover tools from all servers
+    const allTools = await ctx.majk.mcpServers
+      .everywhere()
+      .asAdmin()
+      .discoverTools();
+
+    // Group by server
+    const byServer = {};
+    allTools.forEach(tool => {
+      if (!byServer[tool.serverName]) {
+        byServer[tool.serverName] = [];
+      }
+      byServer[tool.serverName].push(tool);
+    });
+
+    return {
+      toolsByServer: byServer,
+      totalTools: allTools.length,
+      totalServers: Object.keys(byServer).length
+    };
+  });
+```
+
+### Teammate-Specific Tool Execution
+
+```typescript
+export default definePlugin('teammate-tools')
+  .withApi(async (ctx) => ({
+    executeForTeammate: async (teammateId: string, toolName: string, params: any) => {
+      try {
+        const result = await ctx.majk.mcpServers
+          .everywhere()
+          .asTeammate(teammateId)
+          .executeTool(toolName, params);
+
+        return { success: true, result };
+      } catch (error) {
+        return { success: false, error: error.message };
+      }
+    }
+  }));
+```
+
+### Admin Tool Management
+
+```typescript
+export default definePlugin('admin-tools')
+  .withApi(async (ctx) => {
+    const servers = await ctx.majk.mcpServers.list();
+
+    // Discover tools from each server as admin
+    const discoveries = await Promise.all(
+      servers.map(async server => {
+        try {
+          const tools = await server.asAdmin().discoverTools();
+          return { serverId: server.id, serverName: server.name, tools };
+        } catch (error) {
+          return { serverId: server.id, serverName: server.name, error: error.message };
+        }
+      })
+    );
+
+    return { discoveries };
+  });
+```
+
+### Connection Pool Monitoring
+
+```typescript
+// Monitor connection lifecycle
+ctx.majk.eventBus.mcpServers().subscribe(async (event) => {
+  if (event.metadata?.type === 'connection_established') {
+    console.log(`Connection established: ${event.metadata.poolKey}`);
+  }
+
+  if (event.metadata?.type === 'connection_closed') {
+    console.log(`Connection closed: ${event.metadata.poolKey}`);
+  }
+});
+```
+
+## Best Practices
+
+1. **Use appropriate context**: Admin for system operations, teammate for user actions
+2. **Handle errors gracefully**: Tool execution can fail, always wrap in try/catch
+3. **Monitor events**: Subscribe to events for observability
+4. **Leverage everywhere**: Use `.everywhere()` when you don't know which server has a tool
+5. **Clean up connections**: Connections auto-cleanup after 5 min idle, but you can manually disconnect
+6. **Secure secrets**: Never log or expose resolved secrets
+
+## TypeScript Support
+
+Full TypeScript support with type inference:
+
+```typescript
+import type {
+  MCPServerHandle,
+  MCPServerScopedHandle,
+  DiscoveredTool,
+  EverywhereScope,
+  EverywhereScopedHandle
+} from '@majkapp/plugin-kit';
+
+// Type-safe operations
+const server: MCPServerHandle = await ctx.majk.mcpServers.get('id');
+const scope: MCPServerScopedHandle = server.asAdmin();
+const tools: DiscoveredTool[] = await scope.discoverTools();
+```
+
+## Performance Notes
+
+- **Connection pooling**: Connections are reused within the same context
+- **Parallel discovery**: `everywhere().discoverTools()` runs in parallel across servers
+- **Lazy connections**: Connections are created on first use, not on `.asAdmin()/.asTeammate()`
+- **Auto cleanup**: Idle connections are cleaned up after 5 minutes
+
+## Migration from Legacy API
+
+If you were using direct MCP operations:
+
+```typescript
+// OLD
+const tools = await ctx.majk.mcpServers.get('id').then(s => s.getTools());
+
+// NEW - with context awareness
+const tools = await ctx.majk.mcpServers.get('id').then(s => s.asAdmin().discoverTools());
+```

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@majkapp/plugin-kit",
-  "version": "3.2.1",
+  "version": "3.3.1",
   "description": "Pure plugin definition library for MAJK - outputs plugin definitions, not HTTP servers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "plugin-kit": "./dist/generator/cli.js"
+    "plugin-kit": "./dist/generator/cli.js",
+    "majk-plugin-kit": "./dist/generator/cli.js"
   },
   "repository": {
     "type": "git",
@@ -18,12 +19,25 @@
   },
   "files": [
     "dist",
+    "bin",
+    "docs",
     "README.md"
   ],
   "scripts": {
     "build": "tsc && cp src/mcp-dom-agent.js dist/",
     "watch": "tsc --watch",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "promptable": "node ./bin/promptable-cli.js --llm",
+    "promptable:functions": "node ./bin/promptable-cli.js --functions",
+    "promptable:screens": "node ./bin/promptable-cli.js --screens",
+    "promptable:hooks": "node ./bin/promptable-cli.js --hooks",
+    "promptable:context": "node ./bin/promptable-cli.js --context",
+    "promptable:services": "node ./bin/promptable-cli.js --services",
+    "promptable:lifecycle": "node ./bin/promptable-cli.js --lifecycle",
+    "promptable:testing": "node ./bin/promptable-cli.js --testing",
+    "promptable:config": "node ./bin/promptable-cli.js --config",
+    "promptable:api": "node ./bin/promptable-cli.js --api",
+    "promptable:full": "node ./bin/promptable-cli.js --full"
   },
   "keywords": [
     "majk",
@@ -33,6 +47,7 @@
   ],
   "author": "Majk Contributors",
   "dependencies": {
+    "@juleswhite/promptable": "^1.0.2",
     "commander": "^11.1.0",
     "html2canvas": "^1.4.1"
   },