Tools, Resources & Prompts

server.tool({
  name: "read_file",
  description: "Read contents of a file",
  schema: z.object({ path: z.string() }),
  annotations: {
    readOnlyHint: true,      // Doesn't modify state
    openWorldHint: true,     // Can access external data
    requiresAuth: true,      // Needs authentication
  },
}, async ({ path }) => {
  const content = await fs.readFile(path, "utf-8");
  return text(content);
});

// Simple prompt
server.prompt({
  name: "greeting",
  description: "Generate a personalized greeting",
  schema: z.object({
    name: z.string(),
    language: z.string().optional(),
  }),
}, async ({ name, language = "en" }) => {
  const greetings = {
    en: `Hello ${name}!`,
    es: `¡Hola ${name}!`,
    fr: `Bonjour ${name}!`,
  };
  return greetings[language] || greetings.en;
});

// Code review prompt
server.prompt({
  name: "code-review",
  description: "Review code for quality and best practices",
  schema: z.object({
    code: z.string(),
    language: z.string(),
    focus: z.enum(["security", "performance", "readability", "all"]).default("all"),
  }),
}, async ({ code, language, focus }) => {
  return `Please review this ${language} code with a focus on ${focus}:

\`\`\`${language}
${code}
\`\`\`

Provide:
1. Issues found
2. Suggestions for improvement
3. Best practices recommendations
  `;
});

import { MCPClient } from "mcp-use/client";

const client = MCPClient.fromDict({
  mcpServers: {
    prompts: { command: "node", args: ["my-prompts.js"] },
  },
});

await client.createAllSessions();
const session = client.getSession("prompts");

// Get available prompts
const prompts = await session.listPrompts();

// Use a prompt
const greeting = await session.getPrompt("greeting", {
  name: "Alice",
  language: "fr",
});
console.log(greeting.messages[0].content.text);

@server.prompt(
    name="greeting",
    description="Generate a personalized greeting",
)
async def greeting_prompt(
    name: str,
    language: str = "en",
) -> str:
    greetings = {
        "en": f"Hello {name}!",
        "es": f"¡Hola {name}!",
        "fr": f"Bonjour {name}!",
    }
    return greetings.get(language, greetings["en"])

@server.prompt(
    name="code-review",
    description="Review code for issues",
)
async def code_review_prompt(
    code: str,
    language: str,
    focus: str = "all",
) -> str:
    return f"""
Please review this {language} code with a focus on {focus}:

```{language}
{code}

### When to Use Prompts

Prompts are ideal for:

- 📖 **Standardizing** common instructions
- 🔄 **Reusing** complex prompt templates
- 🎯 **Guiding** AI model behavior consistently
- 📦 **Packaging** domain expertise as templates
- 🔗 **Chaining** multiple AI interactions

## Best Practices

<AccordionGroup>
  <Accordion title="Tool Design">
    ✅ **Do:**
    - Keep tools focused on a single responsibility
    - Provide clear, descriptive names and descriptions
    - Use schema validation for all inputs
    - Return structured, predictable outputs
    - Include progress updates for long operations
    
    ❌ **Don't:**
    - Create "god tools" that do too many things
    - Use vague or ambiguous names
    - Return inconsistent data structures
    - Expose dangerous operations without safeguards
  </Accordion>
  
  <Accordion title="Resource Design">
    ✅ **Do:**
    - Use clear, hierarchical URI patterns
    - Provide accurate MIME types
    - Cache expensive resource computations
    - Document URI template parameters
    - Support resource listing
    
    ❌ **Don't:**
    - Use resources for actions with side effects
    - Return different data types for same URI
    - Expose sensitive data without authentication
    - Create deeply nested URI hierarchies
  </Accordion>
  
  <Accordion title="Prompt Design">
    ✅ **Do:**
    - Write clear, specific instructions
    - Include examples when helpful
    - Parameterize variable parts
    - Structure prompts for easy reading
    - Test prompts with actual AI models
    
    ❌ **Don't:**
    - Make prompts too rigid or prescriptive
    - Include redundant or conflicting instructions
    - Assume specific model capabilities
    - Embed sensitive information in templates
  </Accordion>
  
  <Accordion title="Error Handling">
    Always handle errors gracefully and return structured error information. Use try-catch blocks and return structured error objects with success flags, error messages, and error codes. This allows clients to properly handle and display errors to users.
  </Accordion>
</AccordionGroup>

## Examples

### Complete Server with All Three Primitives

```typescript
import { MCPServer, text, object, markdown } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "complete-example",
  version: "1.0.0",
});

// TOOL: Perform actions
server.tool({
  name: "create_task",
  description: "Create a new task",
  schema: z.object({
    title: z.string(),
    priority: z.enum(["low", "medium", "high"]),
  }),
}, async ({ title, priority }) => {
  const task = await db.createTask({ title, priority });
  return object(task);
});

// RESOURCE: Access data
server.resource({
  name: "task-list",
  uri: "app://tasks",
  title: "All Tasks",
}, async () => {
  const tasks = await db.getAllTasks();
  return object(tasks);
});

server.resource({
  name: "task-detail",
  uri: "app://tasks/{taskId}",
  title: "Task Details",
}, async ({ taskId }) => {
  const task = await db.getTask(taskId);
  return object(task);
});

// PROMPT: Guide AI
server.prompt({
  name: "prioritize-tasks",
  description: "Help prioritize tasks",
  schema: z.object({
    tasks: z.array(z.string()),
  }),
}, async ({ tasks }) => {
  return text(`
Please help prioritize these tasks based on urgency and importance:

${tasks.map((t, i) => `${i + 1}. ${t}`).join("\n")}

For each task, suggest:
- Priority level (low/medium/high)
- Reasoning
- Estimated effort
  `);
});

await server.listen(3000);