@tenex-chat/backend 0.9.1

package/src/tools/implementations/mcp_resource_read.ts

@@ -0,0 +1,161 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import type { AISdkTool } from "@/tools/types";
+import { type ToolResponse, createExpectedError } from "@/tools/utils";
+import { extractAgentMcpServers } from "@/prompts/fragments/26-mcp-resources";
+import { getProjectContext } from "@/services/projects";
+import { tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Schema for reading an MCP resource
+ */
+const mcpResourceReadSchema = z.object({
+    serverName: z.string().describe('MCP server name (e.g., "nostr-provider")'),
+    resourceUri: z.string().describe('Resource URI to read (e.g., "file:///path/to/file")'),
+    templateParams: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Parameters for template expansion (e.g., {"pubkey": "abc123"})'),
+    description: z.string().describe("Why you are reading this resource"),
+});
+
+/**
+ * Expand a resource URI template with parameters.
+ * Replaces {param} placeholders with actual values.
+ */
+function expandUriTemplate(uriTemplate: string, params: Record<string, string>): string {
+    let expandedUri = uriTemplate;
+    for (const [key, value] of Object.entries(params)) {
+        expandedUri = expandedUri.replace(new RegExp(`\\{${key}\\}`, "g"), value);
+    }
+    return expandedUri;
+}
+
+/**
+ * Core implementation of reading an MCP resource
+ */
+async function executeReadResource(
+    input: z.infer<typeof mcpResourceReadSchema>,
+    context: ToolExecutionContext
+): Promise<ToolResponse | ReturnType<typeof createExpectedError>> {
+    const { serverName, resourceUri, templateParams, description } = input;
+
+    // Get MCPManager from project context
+    const projectContext = getProjectContext();
+    const mcpManager = projectContext.mcpManager;
+
+    if (!mcpManager) {
+        throw new Error(
+            "MCP manager not available. This is a system error - MCP should be initialized."
+        );
+    }
+
+    // Validate agent has access to this server
+    const agentMcpServers = extractAgentMcpServers(context.agent.tools);
+
+    if (!agentMcpServers.includes(serverName)) {
+        return createExpectedError(
+            `You do not have access to MCP server '${serverName}'. ` +
+                `You can only read resources from servers you have tools from. ` +
+                `Your accessible servers: ${agentMcpServers.length > 0 ? agentMcpServers.join(", ") : "none"}`
+        );
+    }
+
+    // Check if server is running
+    const runningServers = mcpManager.getRunningServers();
+    if (!runningServers.includes(serverName)) {
+        return createExpectedError(
+            `MCP server '${serverName}' is not running. ` +
+                `Running servers: ${runningServers.length > 0 ? runningServers.join(", ") : "none"}`
+        );
+    }
+
+    // Expand template if params provided
+    const expandedUri = templateParams ? expandUriTemplate(resourceUri, templateParams) : resourceUri;
+
+    // Check if URI still has unfilled placeholders
+    if (expandedUri.includes("{") && expandedUri.includes("}")) {
+        return createExpectedError(
+            `Resource URI contains unfilled template parameters: ${expandedUri}. ` +
+                "Please provide all required parameters via templateParams."
+        );
+    }
+
+    try {
+        // Read the resource
+        const result = await mcpManager.readResource(serverName, expandedUri);
+
+        // Format the content for return
+        const formattedContents: string[] = [];
+
+        for (const content of result.contents) {
+            if ("text" in content && typeof content.text === "string") {
+                formattedContents.push(content.text);
+            } else if ("blob" in content && typeof content.blob === "string") {
+                formattedContents.push(
+                    `[Binary content: ${content.blob.length} bytes, MIME type: ${content.mimeType || "unknown"}]`
+                );
+            }
+        }
+
+        return {
+            success: true,
+            message: `Successfully read resource from MCP server '${serverName}'`,
+            resourceUri: expandedUri,
+            serverName,
+            description,
+            content: formattedContents.join("\n\n"),
+            mimeType: result.contents[0]?.mimeType,
+        };
+    } catch (error) {
+        // MCP resource not found or other expected errors
+        const errorMessage = error instanceof Error ? error.message : String(error);
+
+        if (
+            errorMessage.toLowerCase().includes("not found") ||
+            errorMessage.toLowerCase().includes("does not exist")
+        ) {
+            return createExpectedError(
+                `Resource '${expandedUri}' not found on MCP server '${serverName}'. ` +
+                    `Please verify the URI is correct.`
+            );
+        }
+
+        // Other MCP errors - return as expected error (user-facing)
+        return createExpectedError(
+            `Failed to read resource '${expandedUri}' from MCP server '${serverName}': ${errorMessage}`
+        );
+    }
+}
+
+/**
+ * Read content from an MCP resource on-demand.
+ *
+ * This tool provides immediate access to MCP resource content without setting up
+ * a persistent subscription. You can only read resources from MCP servers you have
+ * tools from (servers where you have mcp__serverName__* tools).
+ *
+ * Example use cases:
+ * - Read a configuration file from an MCP server
+ * - Fetch current state from a resource template
+ * - Access documentation or reference data
+ *
+ * For continuous updates, use rag_subscription_create instead.
+ */
+export function createMcpResourceReadTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description:
+            "Read content from an MCP resource. You can only read resources from MCP servers you have tools from.",
+        inputSchema: mcpResourceReadSchema,
+        execute: async (input) => {
+            const result = await executeReadResource(input, context);
+
+            // Handle expected error results
+            if (typeof result === "object" && "type" in result && result.type === "error-text") {
+                return result;
+            }
+
+            return JSON.stringify(result, null, 2);
+        },
+    }) as AISdkTool;
+}

package/src/tools/implementations/mcp_subscribe.ts

@@ -0,0 +1,158 @@
+import type { ConversationToolContext } from "@/tools/types";
+import type { AISdkTool } from "@/tools/types";
+import { type ToolResponse, createExpectedError } from "@/tools/utils";
+import { extractAgentMcpServers } from "@/prompts/fragments/26-mcp-resources";
+import { getProjectContext } from "@/services/projects";
+import { McpSubscriptionService } from "@/services/mcp/McpSubscriptionService";
+import { tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Schema for creating an MCP resource subscription
+ */
+const mcpSubscribeSchema = z.object({
+    serverName: z.string().describe('MCP server name (e.g., "nostr-provider")'),
+    resourceUri: z.string().describe('Resource URI to subscribe to (e.g., "nostr://feed/global")'),
+    description: z.string().describe("Human-readable description of what this subscription monitors"),
+});
+
+/**
+ * Validate that a resource URI has a scheme and non-empty path.
+ * MCP resource URIs follow standard URI format (e.g., "nostr://feed/global", "file:///path").
+ */
+function isValidResourceUri(uri: string): boolean {
+    try {
+        // Check basic structure: must have a scheme (protocol) component
+        const schemeMatch = /^[a-zA-Z][a-zA-Z0-9+\-.]*:/.test(uri);
+        if (!schemeMatch) return false;
+        // Must have something after the scheme
+        const afterScheme = uri.indexOf(":") + 1;
+        return afterScheme < uri.length && uri.substring(afterScheme).trim().length > 0;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Core implementation of MCP resource subscription
+ */
+async function executeSubscribe(
+    input: z.infer<typeof mcpSubscribeSchema>,
+    context: ConversationToolContext
+): Promise<ToolResponse | ReturnType<typeof createExpectedError>> {
+    const { serverName, resourceUri, description } = input;
+
+    // Validate URI format upfront
+    if (!isValidResourceUri(resourceUri)) {
+        return createExpectedError(
+            `Invalid resource URI '${resourceUri}'. ` +
+                "Resource URIs must have a valid scheme (e.g., 'nostr://feed/global', 'file:///path')."
+        );
+    }
+
+    // Get MCPManager from project context
+    const projectContext = getProjectContext();
+    const mcpManager = projectContext.mcpManager;
+
+    if (!mcpManager) {
+        throw new Error(
+            "MCP manager not available. This is a system error - MCP should be initialized."
+        );
+    }
+
+    // Validate agent has access to this server
+    const agentMcpServers = extractAgentMcpServers(context.agent.tools);
+
+    if (!agentMcpServers.includes(serverName)) {
+        return createExpectedError(
+            `You do not have access to MCP server '${serverName}'. ` +
+                "You can only subscribe to resources from servers you have tools from. " +
+                `Your accessible servers: ${agentMcpServers.length > 0 ? agentMcpServers.join(", ") : "none"}`
+        );
+    }
+
+    // Check if server is running
+    const runningServers = mcpManager.getRunningServers();
+    if (!runningServers.includes(serverName)) {
+        return createExpectedError(
+            `MCP server '${serverName}' is not running. ` +
+                `Running servers: ${runningServers.length > 0 ? runningServers.join(", ") : "none"}`
+        );
+    }
+
+    // Get conversation details for subscription context
+    const conversationStore = context.conversationStore;
+    const rootEventId = conversationStore.getRootEventId();
+
+    if (!rootEventId) {
+        return createExpectedError(
+            "Cannot create subscription: conversation has no root event. " +
+                "This subscription must be created within an active conversation."
+        );
+    }
+
+    const projectId = projectContext.project.tagId();
+
+    try {
+        const subscriptionService = McpSubscriptionService.getInstance();
+
+        const subscription = await subscriptionService.createSubscription({
+            agentPubkey: context.agent.pubkey,
+            agentSlug: context.agent.slug,
+            serverName,
+            resourceUri,
+            conversationId: context.conversationId,
+            rootEventId,
+            projectId,
+            description,
+        });
+
+        return {
+            success: true,
+            message: `Successfully created MCP subscription '${subscription.id}'`,
+            subscription: {
+                id: subscription.id,
+                serverName: subscription.serverName,
+                resourceUri: subscription.resourceUri,
+                conversationId: subscription.conversationId,
+                status: subscription.status,
+                description: subscription.description,
+            },
+            hint: `Use mcp_subscription_stop('${subscription.id}') to cancel this subscription.`,
+        };
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return createExpectedError(
+            `Failed to create MCP subscription: ${errorMessage}`
+        );
+    }
+}
+
+/**
+ * Subscribe to MCP resource notifications within the current conversation.
+ *
+ * When the subscribed resource is updated, a notification will be delivered
+ * as a system-reminder message in this conversation, triggering a new
+ * agent execution to handle the update.
+ *
+ * Subscriptions persist across system restarts.
+ */
+export function createMcpSubscribeTool(context: ConversationToolContext): AISdkTool {
+    return tool({
+        description:
+            "Subscribe to MCP resource update notifications. When the resource changes, " +
+            "a notification will be delivered to this conversation. " +
+            "You can only subscribe to resources from MCP servers you have tools from. " +
+            "Subscriptions persist across restarts.",
+        inputSchema: mcpSubscribeSchema,
+        execute: async (input) => {
+            const result = await executeSubscribe(input, context);
+
+            if (typeof result === "object" && "type" in result && result.type === "error-text") {
+                return result;
+            }
+
+            return JSON.stringify(result, null, 2);
+        },
+    }) as AISdkTool;
+}

package/src/tools/implementations/mcp_subscription_stop.ts

@@ -0,0 +1,85 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import type { AISdkTool } from "@/tools/types";
+import { type ToolResponse, createExpectedError } from "@/tools/utils";
+import { McpSubscriptionService } from "@/services/mcp/McpSubscriptionService";
+import { tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Schema for stopping an MCP subscription
+ */
+const mcpSubscriptionStopSchema = z.object({
+    subscriptionId: z.string().describe("The subscription ID to stop (returned by mcp_subscribe)"),
+});
+
+/**
+ * Core implementation of stopping an MCP subscription
+ */
+async function executeStop(
+    input: z.infer<typeof mcpSubscriptionStopSchema>,
+    context: ToolExecutionContext
+): Promise<ToolResponse | ReturnType<typeof createExpectedError>> {
+    const { subscriptionId } = input;
+
+    const subscriptionService = McpSubscriptionService.getInstance();
+    const subscription = subscriptionService.getSubscription(subscriptionId);
+
+    if (!subscription) {
+        return createExpectedError(
+            `Subscription '${subscriptionId}' not found. ` +
+                "Please verify the subscription ID is correct."
+        );
+    }
+
+    // Authorization: only the agent that created the subscription can stop it
+    if (subscription.agentPubkey !== context.agent.pubkey) {
+        return createExpectedError(
+            `You are not authorized to stop subscription '${subscriptionId}'. ` +
+                "Only the agent that created the subscription can stop it."
+        );
+    }
+
+    const success = await subscriptionService.stopSubscription(subscriptionId, context.agent.pubkey);
+
+    if (!success) {
+        return createExpectedError(
+            `Failed to stop subscription '${subscriptionId}'.`
+        );
+    }
+
+    return {
+        success: true,
+        message: `Successfully stopped MCP subscription '${subscriptionId}'`,
+        subscription: {
+            id: subscription.id,
+            serverName: subscription.serverName,
+            resourceUri: subscription.resourceUri,
+            notificationsReceived: subscription.notificationsReceived,
+        },
+    };
+}
+
+/**
+ * Stop an active MCP resource subscription.
+ *
+ * This cancels the subscription and cleans up all persisted state.
+ * The subscription will no longer deliver notifications.
+ */
+export function createMcpSubscriptionStopTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description:
+            "Stop an active MCP resource subscription. " +
+            "Cancels the subscription and removes persisted state. " +
+            "No more notifications will be delivered.",
+        inputSchema: mcpSubscriptionStopSchema,
+        execute: async (input) => {
+            const result = await executeStop(input, context);
+
+            if (typeof result === "object" && "type" in result && result.type === "error-text") {
+                return result;
+            }
+
+            return JSON.stringify(result, null, 2);
+        },
+    }) as AISdkTool;
+}

package/src/tools/implementations/nostr_fetch.ts

@@ -0,0 +1,149 @@
+/**
+ * Nostr Fetch Tool
+ *
+ * Fetches any nostr event by ID and returns formatted or raw output.
+ * Supports various ID formats: nevent, note, naddr, hex, with or without "nostr:" prefix.
+ */
+
+import type { ToolExecutionContext } from "@/tools/types";
+import { getNDK } from "@/nostr";
+import { getPubkeyService } from "@/services/PubkeyService";
+import type { AISdkTool } from "@/tools/types";
+import { createExpectedError, isExpectedNotFoundError } from "@/tools/utils";
+import { logger } from "@/utils/logger";
+import { parseNostrEvent } from "@/utils/nostr-entity-parser";
+import { tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Schema for nostr_fetch tool input
+ */
+const nostrFetchSchema = z.object({
+    eventId: z
+        .string()
+        .describe(
+            "The event ID to fetch. Supports nevent, note, naddr, hex format, with or without 'nostr:' prefix"
+        ),
+    format: z
+        .enum(["raw", "display"])
+        .default("display")
+        .describe(
+            "Output format: 'raw' returns the raw event JSON, 'display' returns human-readable format"
+        ),
+});
+
+type NostrFetchInput = z.infer<typeof nostrFetchSchema>;
+
+/**
+ * Format a tag for display
+ */
+function formatTag(tag: string[]): string {
+    if (tag.length === 0) return "";
+    if (tag.length === 1) return tag[0];
+    return `${tag[0]}=${tag.slice(1).join(",")}`;
+}
+
+/**
+ * Format timestamp to human-readable string
+ */
+function formatTimestamp(unixTimestamp: number): string {
+    const date = new Date(unixTimestamp * 1000);
+    return date
+        .toISOString()
+        .replace("T", " ")
+        .replace(/\.\d{3}Z$/, " UTC");
+}
+
+/**
+ * Execute the nostr_fetch tool
+ * Returns null if event is not found (expected condition)
+ */
+async function executeNostrFetch(input: NostrFetchInput): Promise<string | null> {
+    const { eventId, format } = input;
+
+    const ndk = getNDK();
+
+    // Use the existing parseNostrEvent utility which handles all formats
+    const event = await parseNostrEvent(eventId, ndk);
+
+    if (!event) {
+        // "Event not found" is an expected condition - return null to signal expected error
+        return null;
+    }
+
+    // Return raw event JSON if requested
+    if (format === "raw") {
+        return JSON.stringify(event.rawEvent(), null, 2);
+    }
+
+    // Build display format
+    const pubkeyService = getPubkeyService();
+    const authorName = await pubkeyService.getName(event.pubkey);
+    const timestamp = formatTimestamp(event.created_at || 0);
+
+    // Format tags with bullet points
+    const tagsSection =
+        event.tags.length > 0
+            ? `tags:\n${event.tags.map((tag) => `   * ${formatTag(tag)}`).join("\n")}`
+            : "tags: (none)";
+
+    const displayOutput = [
+        `Event ID: ${event.id}`,
+        `kind: ${event.kind}`,
+        `author: @${authorName}`,
+        `timestamp: ${timestamp}`,
+        "",
+        event.content,
+        "",
+        tagsSection,
+    ].join("\n");
+
+    return displayOutput;
+}
+
+/**
+ * Create the nostr_fetch AI SDK tool
+ */
+export function createNostrFetchTool(_context: ToolExecutionContext): AISdkTool {
+    const toolInstance = tool({
+        description:
+            "Fetches any nostr event by ID. Supports nevent, note, naddr, hex format, " +
+            "with or without 'nostr:' prefix. Returns either raw JSON or a human-readable display format.",
+
+        inputSchema: nostrFetchSchema,
+
+        execute: async (input: NostrFetchInput) => {
+            try {
+                const result = await executeNostrFetch(input);
+
+                // "Event not found" is an expected condition - return error-text
+                if (result === null) {
+                    return createExpectedError(`Event not found: ${input.eventId}`);
+                }
+
+                return result;
+            } catch (error) {
+                // Check if this is an expected "not found" error from a different code path
+                if (isExpectedNotFoundError(error)) {
+                    return createExpectedError(`Event not found: ${input.eventId}`);
+                }
+
+                logger.error("Failed to fetch nostr event", { eventId: input.eventId, error });
+                throw new Error(
+                    `Failed to fetch nostr event: ${error instanceof Error ? error.message : String(error)}`,
+                    { cause: error }
+                );
+            }
+        },
+    });
+
+    Object.defineProperty(toolInstance, "getHumanReadableContent", {
+        value: ({ eventId, format }: NostrFetchInput) => {
+            return `Fetching nostr event ${eventId} (format: ${format || "display"})`;
+        },
+        enumerable: false,
+        configurable: true,
+    });
+
+    return toolInstance as AISdkTool;
+}