repomix-output.txt•483 kB
This file is a merged representation of the entire codebase, combining all repository files into a single document.
Generated by Repomix on: 2025-03-23T02:06:33.503Z
================================================================
File Summary
================================================================
Purpose:
--------
This file contains a packed representation of the entire repository's contents.
It is designed to be easily consumable by AI systems for analysis, code review,
or other automated processes.
File Format:
------------
The content is organized as follows:
1. This summary section
2. Repository information
3. Directory structure
4. Multiple file entries, each consisting of:
a. A separator line (================)
b. The file path (File: path/to/file)
c. Another separator line
d. The full contents of the file
e. A blank line
Usage Guidelines:
-----------------
- This file should be treated as read-only. Any changes should be made to the
original repository files, not this packed version.
- When processing this file, use the file path to distinguish
between different files in the repository.
- Be aware that this file may contain sensitive information. Handle it with
the same level of security as you would the original repository.
Notes:
------
- Some files may have been excluded based on .gitignore rules and Repomix's
configuration.
- Binary files are not included in this packed representation. Please refer to
the Repository Structure section for a complete list of file paths, including
binary files.
Additional Info:
----------------
================================================================
Directory Structure
================================================================
docs/
mcp-sdk-improvements.md
instructions/
checklist.md
Impl.md
mcp_sdk_improvements.md
mcp_server_improvements.md
plan.md
PRD.md
solidity_tic_tac_toe_project.md
src/
templates/
impl-template.md
prd-template.md
clarification.ts
documentation.ts
errors.ts
index-updated.ts
index.ts
mcp-server.ts
phases.ts
registry.ts
resource-handlers.ts
schemas.ts
storage.ts
test-mcp-improved.js
tool-handlers.ts
types.ts
utils.ts
validators.ts
.gitignore
debug.js
MCP-docs.txt
MCP-Typescript-readme.txt
package.json
README.md
test-mcp.js
tsconfig.build.json
tsconfig.json
================================================================
Files
================================================================
================
File: docs/mcp-sdk-improvements.md
================
# MCP SDK Implementation Improvements
## Overview
This document outlines the improvements made to the Vibe-Coder MCP server implementation to better align with the MCP TypeScript SDK best practices and improve overall code quality, maintainability, and type safety.
## Key Improvements
### 1. Tool Handler Registry
We replaced the large switch statement in the main file with a tool handler registry that maps tool names to their handler functions:
```typescript
// Before (in index.ts)
server.setRequestHandler(CallToolRequestSchema, async (request) => {
try {
switch (request.params.name) {
case "start_feature_clarification": {
// Implementation...
}
case "provide_clarification": {
// Implementation...
}
// Many more cases...
}
} catch (error) {
// Error handling...
}
});
// After
// In registry.ts
export class ToolRegistry {
private handlers: Map<string, ToolHandler> = new Map();
register<T>(name: string, handler: ToolHandler<T>): void {
this.handlers.set(name, handler);
}
async execute(name: string, params: any): Promise<any> {
const handler = this.getHandler(name);
if (!handler) {
return createToolErrorResponse(`Unknown tool "${name}"`);
}
return await handler(params);
}
}
// In index-updated.ts
server.setRequestHandler(CallToolRequestSchema, async (request) => {
try {
const toolName = request.params.name;
const toolArguments = request.params.arguments || {};
return await toolRegistry.execute(toolName, toolArguments);
} catch (error) {
// Improved error handling...
}
});
```
### 2. Robust Resource URI Handling
We implemented a robust resource URI handling mechanism using a `ResourceRegistry` class:
```typescript
// In registry.ts
export class ResourceRegistry {
private resources: ResourceRegistryEntry[] = [];
register(template: ResourceTemplate, handler: ResourceHandler): void {
this.resources.push({ template, handler });
}
findMatch(uri: string): { handler: ResourceHandler; params: Record<string, string> } | undefined {
const url = new URL(uri);
for (const { template, handler } of this.resources) {
const match = this.matchTemplate(url, template);
if (match) {
return { handler, params: match };
}
}
return undefined;
}
}
// In index-updated.ts
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
try {
const uri = request.params.uri;
const match = resourceRegistry.findMatch(uri);
if (match) {
return await match.handler(new URL(uri), match.params);
}
return createErrorResponse(ErrorCode.RESOURCE_NOT_FOUND, `Resource not found: ${uri}`);
} catch (error) {
// Improved error handling...
}
});
```
### 3. Improved Error Handling
We standardized error handling across the codebase with consistent JSON-RPC 2.0 error responses:
```typescript
// In errors.ts
export enum ErrorCode {
// JSON-RPC 2.0 Standard Error Codes
PARSE_ERROR = -32700,
INVALID_REQUEST = -32600,
METHOD_NOT_FOUND = -32601,
INVALID_PARAMS = -32602,
INTERNAL_ERROR = -32603,
// Custom Error Codes
VALIDATION_ERROR = -32000,
RESOURCE_NOT_FOUND = -32001,
// More custom error codes...
}
export const createErrorResponse = (
code: ErrorCode,
message: string,
data?: any
): ErrorResponse => {
return {
error: {
code,
message,
data
}
};
};
export const createToolErrorResponse = (
message: string,
details?: any
): ToolErrorResponse => {
return {
content: [{
type: "text",
text: `Error: ${message}`
}],
isError: true
};
};
```
### 4. Stronger Type Safety
We improved type safety throughout the codebase with Zod schemas and branded types:
```typescript
// In schemas.ts
// Branded types for IDs
export type FeatureId = string & { readonly _brand: unique symbol };
export type PhaseId = string & { readonly _brand: unique symbol };
export type TaskId = string & { readonly _brand: unique symbol };
// Zod schemas for validation
export const FeatureSchema = z.object({
id: z.string().refine(isFeatureId, "Invalid feature ID format"),
name: z.string().min(2).max(100),
// More fields...
});
// Type guards
export const isFeatureId = (id: string): id is FeatureId => id.startsWith('feature-');
// ID creators
export const createFeatureId = (id: string): FeatureId => {
if (!isFeatureId(id)) throw new Error(`Invalid feature ID format: ${id}`);
return id as FeatureId;
};
// In utils.ts
export function generateFeatureId(): FeatureId {
const randomPart = Math.random().toString(36).substring(2, 10);
return createFeatureId(`feature-${randomPart}`);
}
```
### 5. Modular Code Structure
We reorganized the codebase into more modular components with clear separation of concerns:
- `registry.ts` - Tool and resource registries
- `tool-handlers.ts` - Tool handler implementations
- `resource-handlers.ts` - Resource handler implementations
- `errors.ts` - Error handling utilities
- `schemas.ts` - Type definitions and validation schemas
## Benefits
1. **Improved Maintainability**: The modular code structure makes it easier to understand, maintain, and extend the codebase.
2. **Better Type Safety**: Branded types and Zod schemas provide stronger type checking and runtime validation.
3. **Consistent Error Handling**: Standardized error responses across the codebase with proper JSON-RPC 2.0 error codes.
4. **More Robust URI Handling**: Proper URI template matching for resources following MCP best practices.
5. **Cleaner Code**: Separation of concerns between different components and elimination of large switch statements.
## Testing
The improvements have been tested with a comprehensive test script (`test-mcp-improved.js`) that verifies the functionality of:
- Tool registration and execution
- Resource URI matching and handling
- Error reporting
- End-to-end workflows (feature clarification, PRD generation, etc.)
## Conclusion
These improvements bring the Vibe-Coder MCP server implementation more in line with MCP TypeScript SDK best practices while also improving overall code quality, maintainability, and type safety.
================
File: instructions/checklist.md
================
# Vibe-Coder MCP Server Implementation Checklist
## Step 1: Server Configuration and Core Structure
- [x] Update server metadata and name
- [x] Define core data types (Feature, ClarificationResponse, Phase, Task)
- [x] Create in-memory storage for features and projects
- [x] Set up directory structure and file organization
- [x] Implement basic utilities (generateId, etc.)
## Step 2: Feature Clarification Implementation
- [x] Create tool for initiating feature clarification
- [x] Implement tool for receiving clarification responses
- [x] Create resource to retrieve clarification status
- [x] Add support for structured questioning workflow
## Step 3: PRD and Implementation Plan Generation
- [x] Create tool for generating PRD document
- [x] Implement tool for creating implementation plan
- [x] Add helper functions for extracting requirements from clarifications
- [x] Implement markdown formatting for documentation generation
- [x] Create template structure for PRDs and implementation plans
## Step 4: Phase Management Implementation
- [x] Implement tool for creating phases
- [x] Add tool for updating phase status
- [x] Create tool for managing tasks within phases
- [x] Implement phase workflow progression logic
## Step 5: Resource Implementation
- [x] Create resources for listing all features
- [x] Add resources for accessing feature details
- [x] Implement resources for retrieving PRDs
- [x] Create resources for retrieving implementation plans
- [x] Add support for phase and task status viewing
## Step 6: Tool Implementation
- [x] Define all tool schemas and validations
- [x] Implement error handling for tools
- [x] Ensure proper argument validation
- [x] Add support for tool discoverability
- [x] Test tool invocations with example data
## Step 7: Prompt Implementation
- [ ] Create clarify_feature prompt
- [ ] Implement generate_prd_template prompt
- [ ] Add phase_implementation_guide prompt
- [ ] Ensure prompts are well-structured for LLM use
## Testing and Documentation
- [ ] Test each tool individually
- [ ] Test complete workflows end-to-end
- [ ] Create example usage documentation
- [ ] Add README with setup and usage instructions
================
File: instructions/Impl.md
================
# Vibe-Coder MCP Server Implementation Plan
This document outlines the step-by-step implementation strategy for building the Vibe-Coder MCP Server using the Model Context Protocol specification for TypeScript. Each phase represents a discrete, focused task with clear checklists, coding standards, and review processes.
---
## Phase 1: Environment Setup and Repository Initialization
### Objectives
- Set up the development environment and repository.
- Install required dependencies (including the MCP TypeScript SDK).
- Establish a working base by validating a simple MCP server.
### Tasks
- [ ] **Repository Initialization:**
- Create a new repository or branch dedicated to the Vibe-Coder feature.
- Follow the naming convention: `feature/vibe-coder`.
- [ ] **Environment Setup:**
- Ensure Node.js and npm are installed.
- Install the MCP TypeScript SDK:
```bash
npm install @modelcontextprotocol/sdk
```
- [ ] **Basic MCP Server Setup:**
- Create a minimal MCP server (e.g., an Echo server) based on the MCP TypeScript examples.
- Validate that the server correctly processes simple requests (using `StdioServerTransport` or HTTP with SSE).
- [ ] **Establish Branching Guidelines:**
- Document and enforce the branch naming convention (e.g., each phase creates a branch off the main feature branch).
### Code Style & Practices
- Use TypeScript best practices.
- Follow the MCP SDK examples for a clean code structure.
- Maintain clear commit messages describing changes made.
---
## Phase 2: Implement Feature Request Clarification Module
### Objectives
- Build a module to interactively engage users to clarify feature requests.
- Record and structure user responses to refine the feature scope.
### Tasks
- [ ] **Design Clarification Workflow:**
- Define a flow that asks iterative questions and records responses.
- Use clear prompts to ensure the user’s requirements are well defined.
- [ ] **Implement Clarification Module:**
- Create a dedicated TypeScript module (e.g., `clarification.ts`) that:
- Sends questions to the user.
- Stores responses in a structured format (e.g., JSON).
- [ ] **Integrate with MCP Tools/Prompts:**
- Utilize MCP prompts to ask clarifying questions if appropriate.
- [ ] **Testing:**
- Create unit tests that simulate user interactions and verify the response recording.
### Checklist
- [ ] Define a list of initial questions.
- [ ] Implement response recording with validation.
- [ ] Integrate and test prompt handling via MCP.
---
## Phase 3: PRD and Documentation Generation Module
### Objectives
- Automate the generation and saving of PRD documentation.
- Ensure that the PRD is saved in the correct folder with the proper naming convention.
### Tasks
- [ ] **Template Creation:**
- Develop a Markdown template for the PRD (reuse sections from the PRD document).
- [ ] **File Generation Module:**
- Create a module (e.g., `docGenerator.ts`) that:
- Populates the template with feature details.
- Saves the file to `vibe-instructions/` with a name like `01_VibeCoder_PRD.md`.
- [ ] **Validation:**
- Implement checks to ensure the generated file meets naming and format requirements.
### Checklist
- [ ] Define PRD template sections.
- [ ] Write file I/O functions to save Markdown files.
- [ ] Test file generation with dummy data.
---
## Phase 4: MCP Server Integration and Feature Implementation
### Objectives
- Integrate the clarified feature request and documentation modules into the MCP server.
- Build the core functionality of the Vibe-Coder using the MCP TypeScript SDK.
### Tasks
- [ ] **Server Initialization:**
- Initialize an MCP server instance using the MCP TypeScript SDK.
- Example:
```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = new McpServer({
name: "Vibe-Coder",
version: "1.0.0"
});
```
- [ ] **Integrate Clarification Module:**
- Connect the clarification module to the MCP server’s tool or prompt mechanisms.
- [ ] **Feature Request Handling:**
- Define MCP tools or resources to process and store feature requests and clarifications.
- [ ] **Documentation Integration:**
- Link the generated PRD and Implementation Plan documents to the MCP server’s workflow (e.g., as resources that can be fetched by clients).
- [ ] **Testing:**
- Test server interactions using both local transports (stdio) and, if applicable, HTTP with SSE.
### Checklist
- [ ] Initialize MCP server using the TypeScript SDK.
- [ ] Integrate the clarification module with MCP prompts.
- [ ] Validate tool/resource functionality with sample requests.
- [ ] Ensure documentation files are retrievable by the server.
---
## Phase 5: Phased Implementation Workflow and Branching
### Objectives
- Establish and enforce the phased development workflow.
- Ensure each phase’s changes are documented, committed, and reviewed before merging.
### Tasks
- [ ] **Branch Creation:**
- Create a new branch for each phase from the main feature branch (e.g., `phase/clarification`, `phase/documentation`, `phase/integration`).
- [ ] **Commit Process:**
- Write detailed commit messages that reference the checklist and completed tasks.
- [ ] **Code Reviews:**
- Request targeted code reviews for each phase.
- Share the PRD, phase-specific Implementation Plan, and corresponding code changes.
- [ ] **Merge and History:**
- Merge phase branches into the feature branch once approved.
- Retain phase branches for historical reference.
### Checklist
- [ ] Create and document branch naming conventions.
- [ ] Write commit message guidelines.
- [ ] Schedule code reviews for each completed phase.
- [ ] Merge phase branches after successful review.
---
## Phase 6: Finalization, Project Summary, and Feature README
### Objectives
- Complete the feature by updating project documentation.
- Summarize the new functionality and provide usage instructions.
### Tasks
- [ ] **Project README Update:**
- Update the main project README with a summary of the Vibe-Coder feature.
- [ ] **Feature-Specific README:**
- Create a dedicated README that details:
- The new feature’s functionality.
- How to use and integrate the Vibe-Coder MCP Server.
- References to the PRD and Implementation Plan.
- [ ] **Final Code Review:**
- Request a comprehensive review covering the entire feature.
- Ensure all documentation, tests, and code changes meet the defined standards.
### Checklist
- [ ] Write a project summary for the new feature.
- [ ] Generate a feature-specific README with detailed instructions.
- [ ] Conduct a final, comprehensive code review.
- [ ] Merge final changes into the main branch.
---
## Summary
This Implementation Plan breaks down the development of the Vibe-Coder MCP Server into six discrete phases—from environment setup to final documentation and code review. Each phase is accompanied by detailed tasks and checklists, ensuring adherence to the MCP specification for TypeScript and maintaining a clear, organized workflow.
By following this plan, the development team will be able to iteratively build, test, and review the feature, ensuring that it is robust, well-documented, and compliant with established coding standards and best practices.
================
File: instructions/mcp_sdk_improvements.md
================
# Implementation Plan for MCP SDK Improvements
## 1. Replace Switch Statement with Tool Handler Map
### Tasks:
- [x] Create a tool handler type definition in `types.ts`
- [x] Create a tools registry object that maps tool names to handler functions
- [x] Refactor the `CallToolRequestSchema` handler to use this registry
- [x] Add validation and error handling for unknown tools
- [x] Update tool registration to automatically populate the registry
- [ ] Test all tools to ensure functionality remains the same
## 2. Implement Robust URI Parsing
### Tasks:
- [x] Create a `ResourceRegistry` class that handles URI templates and matching
- [x] Update resource definitions to use proper URI templates
- [x] Implement pattern matching for incoming resource URIs
- [x] Refactor `ReadResourceRequestSchema` handler to use the registry
- [x] Add validation and error handling for malformed URIs
- [ ] Test with various URI patterns to ensure correct matching
## 3. Improve Error Handling Consistency
### Tasks:
- [x] Define standard error response types following JSON-RPC 2.0 spec
- [x] Create utility functions for generating consistent error responses
- [x] Update all error returns to use these utility functions
- [x] Ensure error codes are appropriate and consistent
- [x] Add more detailed error messages with context
- [x] Improve validation error reporting
- [ ] Test error scenarios to verify consistent responses
## 4. Use More Specific Types and Reduce Type Assertions
### Tasks:
- [x] Create Zod schemas for core data structures (Feature, Phase, Task)
- [x] Implement branded types for identifiers (FeatureId, PhaseId, TaskId)
- [x] Replace string types with more specific types where appropriate
- [ ] Eliminate `@ts-ignore` comments by fixing underlying type issues
- [x] Add runtime type validation at critical boundaries
- [x] Update function signatures to use the new types
- [ ] Test type safety with various inputs
## Implementation Order and Dependencies
1. **First Phase**: Type improvements (foundation for other changes) ✅
- Implement specific types and Zod schemas ✅
- Remove type assertions where possible ✅
2. **Second Phase**: Error handling improvements ✅
- Create error utilities ✅
- Update error responses to use common format ✅
3. **Third Phase**: Resource URI handling ✅
- Implement resource registry ✅
- Update URI parsing and matching ✅
4. **Fourth Phase**: Tool handler refactoring ✅
- Create tools registry ✅
- Refactor call tool request handling ✅
## Next Steps
1. Testing strategy:
- Create unit tests for each component
- Test edge cases and error scenarios
- Compare outputs before and after changes to ensure consistency
2. Create a PR with the changes
- Update the documentation
- Add examples of using the new APIs
================
File: instructions/mcp_server_improvements.md
================
# Implementation Plan: MCP Server Improvements
## Phase 1: Critical Fixes (High Priority)
### Task 1: Fix Resource Registry Import
- [x] Update `index-updated.ts` to import `resourceRegistry` at the top of the file
- [x] Remove the `require` call from the `ReadResourceRequestSchema` handler
- [x] Test the handler to ensure it works properly with the imported registry
### Task 2: Improve Error Handling
- [x] Modify `documentation.ts` to throw proper errors when template loading fails
- [x] Update `clarification.ts` to throw specific errors and return completion objects
- [x] Add try/catch blocks where necessary to handle these new errors properly
- [ ] Test the error handling with invalid inputs
## Phase 2: Architecture Improvements (Medium Priority)
### Task 1: Enhance Tool Registry with Metadata
- [x] Modify the `ToolRegistry` class in `registry.ts` to store and manage tool metadata
- [x] Add `listTools()` method to return all registered tools with their metadata
- [x] Update the `register` method to accept description and input schema
- [x] Modify `index-updated.ts` to use `toolRegistry.listTools()` in the handler
### Task 2: Implement Self-Registration Pattern
- [ ] Create a new file `tool-registry.ts` to define the tool registration process
- [ ] Modify each tool handler file to self-register on import
- [ ] Remove the centralized `registerToolHandlers` function
- [ ] Repeat the same pattern for resource handlers
- [ ] Test that all tools and resources are properly registered
## Phase 3: Enhance Testing Framework (Medium Priority)
### Task 1: Set Up Jest Testing Framework
- [ ] Install Jest and related dependencies
- [ ] Configure Jest for TypeScript testing
- [ ] Create a basic test setup file with server startup/shutdown
### Task 2: Migrate Existing Tests to Jest
- [ ] Convert the `test-mcp-improved.js` to use Jest's test structure
- [ ] Replace timeouts with proper async/await and promises
- [ ] Add assertions to verify responses
### Task 3: Add Comprehensive Tests
- [ ] Add tests for error cases and edge conditions
- [ ] Test URI matching with various patterns
- [ ] Test tool execution with valid and invalid inputs
- [ ] Test resource handling with various URIs
## Phase 4: Additional Improvements (Lower Priority)
### Task 1: Implement Better Templating
- [ ] Research and select an appropriate templating engine
- [ ] Update `documentation.ts` to use the selected templating engine
- [ ] Create improved templates with proper variable handling
### Task 2: Ensure Consistent Code Style
- [ ] Apply consistent naming conventions throughout the codebase
- [ ] Add JSDoc comments to all functions and classes
- [ ] Set up a code formatter like Prettier
## Implementation Steps
### For Phase 1:
1. Fix Resource Registry Import: ✅
```typescript
// At the top of index-updated.ts
import { toolRegistry, resourceRegistry } from './registry.js';
// In the ReadResourceRequestSchema handler
const match = resourceRegistry.findMatch(uri);
```
2. Improve Error Handling: ✅
```typescript
// In documentation.ts
function loadTemplate(templateName: string): string {
try {
return fs.readFileSync(templatePath, 'utf-8');
} catch (error) {
throw new Error(`Failed to load template ${templateName}: ${error}`);
}
}
// In clarification.ts
export function getNextClarificationQuestion(feature: Feature): string | { done: true } {
if (!feature.clarificationResponses) {
throw new Error(`Feature is missing clarificationResponses array: ${feature.id}`);
}
if (feature.clarificationResponses.length >= DEFAULT_CLARIFICATION_QUESTIONS.length) {
return { done: true };
}
return DEFAULT_CLARIFICATION_QUESTIONS[feature.clarificationResponses.length];
}
```
### For Phase 2:
1. Enhance Tool Registry: ✅
```typescript
// In registry.ts
export class ToolRegistry {
private handlers: Map<string, ToolHandler> = new Map();
private toolMetadata: Map<string, { description: string; inputSchema: any }> = new Map();
register<T>(
name: string,
handler: ToolHandler<T>,
description: string,
inputSchema: any
): void {
this.handlers.set(name, handler);
this.toolMetadata.set(name, { description, inputSchema });
}
// ... existing methods ...
listTools(): { name: string; description: string; inputSchema: any }[] {
return Array.from(this.handlers.keys()).map((name) => {
const metadata = this.toolMetadata.get(name);
return {
name,
description: metadata?.description || "No description provided.",
inputSchema: metadata?.inputSchema || {},
};
});
}
}
// In index-updated.ts
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: toolRegistry.listTools(),
};
});
```
## Timeline and Dependencies
1. Phase 1 (1-2 days): ✅
- Resource registry fix: 0.5 day ✅
- Error handling improvements: 1-1.5 days ✅
- No dependencies
2. Phase 2 (2-3 days): 🔄
- Tool registry enhancements: 1-1.5 days ✅
- Self-registration pattern: 1-1.5 days 🔄
- Depends on Phase 1 completion ✅
================
File: instructions/plan.md
================
# Vibe-Coder MCP Server Implementation Plan
After examining the existing template MCP server and the provided documents, I'll outline a detailed implementation plan for creating the Vibe-Coder MCP server according to the PRD and Implementation documents.
## Overview
The Vibe-Coder MCP server will guide casual coders through a structured development process using features exposed via the Model Context Protocol. It will transform the existing notes system into a comprehensive development workflow tool, helping LLMs organize code development through clarification workflows, documentation generation, and phased implementation.
## Implementation Steps
### Step 1: Server Configuration and Core Structure
I'll start by modifying the existing MCP server to align with the Vibe-Coder requirements:
1. Update server metadata and capabilities
2. Define core data structures for features, PRDs, and implementation plans
3. Create in-memory storage for projects and their phases
```typescript
// Core data types
type Feature = {
id: string;
name: string;
description: string;
clarificationResponses: ClarificationResponse[];
prdDoc?: string;
implDoc?: string;
phases: Phase[];
};
type ClarificationResponse = {
question: string;
answer: string;
};
type Phase = {
id: string;
name: string;
description: string;
tasks: Task[];
status: "pending" | "in_progress" | "completed" | "reviewed";
};
type Task = {
description: string;
completed: boolean;
};
// In-memory storage
const features: { [id: string]: Feature } = {};
```
### Step 2: Feature Clarification Implementation
The clarification module will use MCP tools to engage users in iterative questioning:
1. Create a tool to initiate feature clarification
2. Implement a tool to receive clarification responses
3. Create a resource to retrieve clarification status
```typescript
// Tool for initiating clarification
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === "start_feature_clarification") {
const featureName = String(request.params.arguments?.featureName || "");
const featureId = generateId();
features[featureId] = {
id: featureId,
name: featureName,
description: String(request.params.arguments?.initialDescription || ""),
clarificationResponses: [],
phases: []
};
// Return first clarification question
return {
content: [{
type: "text",
text: `Feature ID: ${featureId}\n\nLet's clarify your feature request. What specific problem does this feature solve?`
}]
};
}
// Handle other tools...
});
```
### Step 3: PRD and Implementation Plan Generation
Implement tools to generate documentation based on clarification responses:
1. Create a tool to generate the PRD document
2. Implement a tool to create the implementation plan
3. Add resources to access these documents
```typescript
// Tool for generating PRD
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === "generate_prd") {
const featureId = String(request.params.arguments?.featureId);
const feature = features[featureId];
if (!feature) {
throw new Error("Feature not found");
}
// Generate PRD content based on clarification responses
const prdContent = generatePRD(feature);
feature.prdDoc = prdContent;
return {
content: [{
type: "text",
text: `PRD generated successfully for ${feature.name}. You can view it using the "feature_prd" resource.`
}]
};
}
// Similar implementation for implementation plan generation...
});
```
### Step 4: Phase Management Implementation
Create tools to manage development phases:
1. Implement a tool to create phases
2. Add a tool to update phase status
3. Create resources to view phase details
```typescript
// Tool for creating a new phase
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === "create_phase") {
const featureId = String(request.params.arguments?.featureId);
const phaseName = String(request.params.arguments?.name);
const phaseDescription = String(request.params.arguments?.description);
const tasks = JSON.parse(String(request.params.arguments?.tasks || "[]"));
const feature = features[featureId];
if (!feature) {
throw new Error("Feature not found");
}
const phaseId = generateId();
feature.phases.push({
id: phaseId,
name: phaseName,
description: phaseDescription,
tasks: tasks.map((task: string) => ({ description: task, completed: false })),
status: "pending"
});
return {
content: [{
type: "text",
text: `Phase "${phaseName}" created with ID: ${phaseId}`
}]
};
}
// Handle other tools...
});
```
### Step 5: Resource Implementation
Implement resources to retrieve feature data, PRDs, and implementation plans:
1. Create resources for listing all features
2. Add resources for accessing feature details
3. Implement resources for retrieving PRDs and implementation plans
```typescript
// Handler for listing available features as resources
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: "features://list",
mimeType: "text/plain",
name: "Features List",
description: "Lists all features being developed"
},
...Object.values(features).flatMap(feature => [
{
uri: `feature://${feature.id}`,
mimeType: "text/plain",
name: feature.name,
description: `Details about feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/prd`,
mimeType: "text/markdown",
name: `${feature.name} PRD`,
description: `PRD document for feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/implementation`,
mimeType: "text/markdown",
name: `${feature.name} Implementation Plan`,
description: `Implementation plan for feature: ${feature.name}`
}
])
]
};
});
// Handler for reading feature resources
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
const url = new URL(request.params.uri);
// Handle various resource types...
if (url.protocol === "features:") {
if (url.pathname === "/list") {
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: Object.values(features).map(f => `${f.id}: ${f.name}`).join("\n")
}]
};
}
}
if (url.protocol === "feature:") {
const parts = url.pathname.split('/').filter(Boolean);
const featureId = parts[0];
const feature = features[featureId];
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
if (parts.length === 1) {
// Return feature details
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: formatFeatureDetails(feature)
}]
};
}
if (parts[1] === "prd") {
return {
contents: [{
uri: request.params.uri,
mimeType: "text/markdown",
text: feature.prdDoc || "PRD not yet generated"
}]
};
}
// Handle other resource types...
}
throw new Error("Resource not found");
});
```
### Step 6: Tool Implementation
Expose the main tools for interacting with the Vibe-Coder MCP server:
```typescript
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: "start_feature_clarification",
description: "Start the clarification process for a new feature",
inputSchema: {
type: "object",
properties: {
featureName: {
type: "string",
description: "Name of the feature"
},
initialDescription: {
type: "string",
description: "Initial description of the feature"
}
},
required: ["featureName"]
}
},
{
name: "provide_clarification",
description: "Provide answer to a clarification question",
inputSchema: {
type: "object",
properties: {
featureId: {
type: "string",
description: "ID of the feature"
},
question: {
type: "string",
description: "Clarification question"
},
answer: {
type: "string",
description: "Answer to the clarification question"
}
},
required: ["featureId", "question", "answer"]
}
},
{
name: "generate_prd",
description: "Generate a PRD document based on clarification responses",
inputSchema: {
type: "object",
properties: {
featureId: {
type: "string",
description: "ID of the feature"
}
},
required: ["featureId"]
}
},
{
name: "generate_implementation_plan",
description: "Generate an implementation plan document",
inputSchema: {
type: "object",
properties: {
featureId: {
type: "string",
description: "ID of the feature"
}
},
required: ["featureId"]
}
},
{
name: "create_phase",
description: "Create a new implementation phase",
inputSchema: {
type: "object",
properties: {
featureId: {
type: "string",
description: "ID of the feature"
},
name: {
type: "string",
description: "Name of the phase"
},
description: {
type: "string",
description: "Description of the phase"
},
tasks: {
type: "string",
description: "JSON array of task descriptions"
}
},
required: ["featureId", "name", "description"]
}
},
{
name: "update_phase_status",
description: "Update the status of a phase",
inputSchema: {
type: "object",
properties: {
featureId: {
type: "string",
description: "ID of the feature"
},
phaseId: {
type: "string",
description: "ID of the phase"
},
status: {
type: "string",
description: "New status (pending, in_progress, completed, reviewed)"
}
},
required: ["featureId", "phaseId", "status"]
}
},
{
name: "update_task_status",
description: "Mark a task as completed or not completed",
inputSchema: {
type: "object",
properties: {
featureId: {
type: "string",
description: "ID of the feature"
},
phaseId: {
type: "string",
description: "ID of the phase"
},
taskIndex: {
type: "number",
description: "Index of the task"
},
completed: {
type: "boolean",
description: "Whether the task is completed"
}
},
required: ["featureId", "phaseId", "taskIndex", "completed"]
}
}
]
};
});
```
### Step 7: Prompt Implementation
Create prompts to guide users through the development workflow:
```typescript
server.setRequestHandler(ListPromptsRequestSchema, async () => {
return {
prompts: [
{
name: "clarify_feature",
description: "Guide to clarify a feature request through questioning"
},
{
name: "generate_prd_template",
description: "Guide to generate a PRD document from clarifications"
},
{
name: "phase_implementation_guide",
description: "Guide for implementing a development phase"
}
]
};
});
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
if (request.params.name === "clarify_feature") {
return {
messages: [
{
role: "user",
content: {
type: "text",
text: "Help me clarify this feature request by asking questions about:"
}
},
{
role: "user",
content: {
type: "text",
text: "1. The specific problem it solves\n2. The target users\n3. Key requirements\n4. Success criteria\n5. Technical constraints\n\nAsk one question at a time, analyze the response, then proceed to the next most relevant question."
}
}
]
};
}
// Handle other prompts...
});
```
## Helper Functions to Implement
Here are the core helper functions needed for the implementation:
```typescript
// Generate unique IDs
function generateId(): string {
return Math.random().toString(36).substring(2, 15);
}
// Format feature details for display
function formatFeatureDetails(feature: Feature): string {
return `
Feature: ${feature.name}
ID: ${feature.id}
Description: ${feature.description}
Clarification Responses:
${feature.clarificationResponses.map(cr => `Q: ${cr.question}\nA: ${cr.answer}`).join('\n\n')}
Phases (${feature.phases.length}):
${feature.phases.map(p => `- ${p.name} (${p.status}): ${p.tasks.filter(t => t.completed).length}/${p.tasks.length} tasks completed`).join('\n')}
`;
}
// Generate PRD document
function generatePRD(feature: Feature): string {
const clarifications = feature.clarificationResponses;
return `# ${feature.name} PRD
## 1. Introduction
${feature.description}
## 2. Feature Objectives
${extractObjectivesFromClarifications(clarifications)}
## 3. Scope and Requirements
${extractRequirementsFromClarifications(clarifications)}
## 4. High-Level Implementation Overview
To be determined based on the implementation plan.
## 5. Feedback and Iteration Process
This PRD will be updated as the implementation progresses and feedback is received.
`;
}
// Generate implementation plan
function generateImplementationPlan(feature: Feature): string {
// Similar to PRD generation, but creating an implementation plan
// ...
}
// Extract objectives from clarification responses
function extractObjectivesFromClarifications(responses: ClarificationResponse[]): string {
// Logic to extract objectives based on responses to clarification questions
// ...
}
// Extract requirements from clarification responses
function extractRequirementsFromClarifications(responses: ClarificationResponse[]): string {
// Logic to extract requirements based on responses to clarification questions
// ...
}
```
## File Structure
The implementation will be organized as follows:
```
src/
├── index.ts # Main server entry point
├── types.ts # Type definitions
├── storage.ts # Feature storage management
├── clarification.ts # Clarification workflow logic
├── documentation.ts # PRD and implementation plan generation
├── phases.ts # Phase and task management
├── utils.ts # Helper utilities
├── handlers/ # MCP request handlers
│ ├── resources.ts # Resource request handlers
│ ├── tools.ts # Tool request handlers
│ └── prompts.ts # Prompt request handlers
└── templates/ # Documentation templates
├── prd-template.md # PRD document template
└── impl-template.md # Implementation plan template
```
## Implementation Timeline
1. **Week 1**: Set up core server structure and data models
2. **Week 2**: Implement feature clarification workflow
3. **Week 3**: Build PRD and implementation plan generation
4. **Week 4**: Develop phase management functionality
5. **Week 5**: Complete resources and refinements
6. **Week 6**: Testing and documentation
## Next Steps
1. Start by modifying the existing server to match the Vibe-Coder requirements
2. Implement the core data structures and storage
3. Build feature clarification tools and resources
4. Add document generation capabilities
5. Implement phase management tools
6. Complete integration with MCP
================
File: instructions/PRD.md
================
# Vibe-Coder MCP Server PRD
## 1. Introduction
The Vibe-Coder MCP Server is designed to help casual, LLM-based coders build new features in an organized, clean, and safe manner. By leveraging the Model Context Protocol (MCP), this server guides users through a structured process—from clarifying feature requests to implementing them in discrete, verifiable phases. This document defines the product requirements and lays the groundwork for the detailed implementation plan.
## 2. Feature Objectives
- **Assist LLM-based Coders:** Enable casual developers (vibe coders) to request and build features efficiently using an LLM-driven workflow.
- **Structured Development:** Organize the feature creation process into clearly defined stages, ensuring each phase is documented, reviewed, and implemented according to best practices.
- **Clean and Safe Code:** Enforce code quality standards, safe implementation practices, and thorough documentation throughout the development cycle.
- **Iterative Clarification:** Engage users in rounds of questions to continuously refine and narrow down the feature requirements.
## 3. Scope and Requirements
### 3.1 Feature Request Clarification
- **Iterative Engagement:**
- The system will prompt users with follow-up questions to clarify the exact goals and nuances of the requested feature.
- User responses will be recorded and used to refine the feature’s scope.
### 3.2 PRD Documentation
- **Concise PRD Drafting:**
- Develop a narrow and specific PRD that captures:
- **Feature Objectives:** A clear description of what the feature should achieve.
- **Detailed Requirements:** Specific, actionable requirements and constraints.
- **Documentation References:** Links or references to relevant code formats, style guides, and best practices.
- **File Organization:**
- Save the PRD as a Markdown file using the naming convention:
`StepNumber_FeatureName_PRD.md`
*(Example: “01_VibeCoder_PRD.md”)*
### 3.3 Implementation Specification
- **Phased Breakdown:**
- Divide the feature’s implementation into discrete phases, where each phase addresses a single focused task.
- **Checklists and Standards:**
- For each phase, include a checklist detailing:
- Task requirements
- Code style and practices that must be adhered to
- **Separate Documentation:**
- Save the implementation plan in its own Markdown file, following the naming convention:
`StepNumber_FeatureName_Implementation.md`
## 4. High-Level Implementation Overview
### 4.1 Development Workflow and Branching Strategy
- **Feature Branch:**
- Begin each new feature on a dedicated branch.
- **Phase Branches:**
- For every discrete phase within a feature, create a new branch off the feature branch.
- **Commit and Code Review Process:**
- After completing each phase:
- Create detailed git commits capturing all changes.
- Request a targeted code review that includes the PRD, the phase-specific implementation plan, and the relevant code changes.
- Merge the phase branch back into the feature branch (retain phase branches for history).
### 4.2 Finalization Process
- **Project Summary:**
- Upon feature completion, update the project README with a summary of the new functionality.
- **Feature-Specific README:**
- Create a dedicated README that details:
- The new feature’s functionality
- How to use the feature
- The adherence to the documented practices and checklists
- **Final Code Review:**
- Conduct a comprehensive code review covering all documentation and code, ensuring only the relevant portions are evaluated.
## 5. Structuring the MCP for LLM Compliance
To ensure the LLM follows the outlined instructions accurately, the following practices are essential:
- **Clear Hierarchical Sections:**
- Use distinct headings and subheadings for each major section (e.g., Introduction, Objectives, Scope, etc.).
- **Step-by-Step Breakdown:**
- Organize tasks in numbered steps with clear, actionable directives (e.g., “Draft the PRD,” “Create phase-specific branches”).
- **Consistent Naming Conventions:**
- Specify precise file and branch naming formats to eliminate ambiguity.
- **Imperative Language:**
- Use direct commands (e.g., “Create,” “Define,” “Save,” “Merge”) to ensure clarity.
- **Checklists and Examples:**
- Provide concrete examples or templates for PRD sections, implementation plans, and commit messages to serve as models.
- **Feedback Loops:**
- Include instructions to ask clarifying questions if any step is ambiguous.
- **Documentation Focus:**
- Emphasize thorough documentation of every phase with clear checklists and version control histories.
## 6. Feedback and Iteration Process
- **User Feedback Integration:**
- Regularly incorporate user feedback to refine feature objectives and requirements.
- **Iterative Updates:**
- Update both the PRD and the implementation plan as new details emerge during the development process.
- **Review and Approval:**
- Ensure that each phase is reviewed and approved before moving to subsequent phases.
## 7. Appendix
### 7.1 File Naming Conventions
- **PRD File:** `StepNumber_FeatureName_PRD.md`
*(Example: “01_VibeCoder_PRD.md”)*
- **Implementation Plan File:** `StepNumber_FeatureName_Implementation.md`
### 7.2 Example Checklists and Templates
- **Feature Request Checklist:**
- [ ] Define feature objective
- [ ] Clarify user requirements through iterative questions
- [ ] Record user responses for scope refinement
- **Phase Implementation Checklist:**
- [ ] Define phase-specific tasks
- [ ] Outline required code standards and practices
- [ ] Document progress with commit messages
- [ ] Request targeted code review
- [ ] Merge phase branch into feature branch after review
================
File: instructions/solidity_tic_tac_toe_project.md
================
# Solidity Tic Tac Toe Project
**Feature ID:** feature-hy5l98td
## Clarification Responses
### What specific problem does this feature solve?
This feature solves the problem of creating verifiable, tamper-proof gaming experiences on blockchain. It demonstrates how traditional games can be implemented in a decentralized manner where the game state and rules are enforced by smart contracts rather than a central server, ensuring fair play and transparent outcomes.
### Who are the target users for this feature?
The target users are:
1) Blockchain enthusiasts who want to experience decentralized gaming
2) Ethereum developers learning how to implement game logic in smart contracts
3) Educational platforms teaching blockchain concepts through familiar games
4) Players interested in crypto-gaming who want to try simple blockchain games with potential for token rewards
### What are the key requirements for this feature?
Key requirements include:
1) A Solidity smart contract that implements the complete Tic Tac Toe game logic
2) Functions for player registration and turn management
3) Win condition detection and game state verification
4) Prevention of illegal moves and proper handling of drawn games
5) Option for players to wager ETH on game outcomes
6) Events that can be used by a frontend to track game progress
7) Gas-efficient implementation to minimize transaction costs
### What are the technical constraints or considerations?
Technical constraints include:
1) Gas optimization is critical - each move costs ETH to execute
2) The contract must be compatible with Solidity 0.8.x and deployable to Ethereum and compatible chains like Polygon
3) State management must be efficient as blockchain storage is expensive
4) Proper access control is needed to ensure only valid players can make moves in their own games
5) Time constraints should be considered to prevent abandoned games
6) Input validation is crucial to prevent exploits or illegal game states
7) No external dependencies should be required beyond standard Solidity libraries
### How will we measure the success of this feature?
Success will be measured by:
1) Successful deployment of the contract to a testnet with verified gameplay
2) Completion of full games without errors or invalid states
3) Gas usage below 200,000 gas per move
4) Proper detection of all win conditions and draws
5) Correct handling of wagers and payouts
6) Successful integration with a basic web frontend for demonstration
7) Security audit passing without critical vulnerabilities
8) Documentation that allows developers to understand and interact with the contract
### Are there any dependencies on other features or systems?
Dependencies include:
1) Ethereum or compatible blockchain network for deployment
2) Solidity compiler version 0.8.x
3) Hardhat or Truffle for development, testing and deployment
4) Ethers.js or Web3.js for frontend integration
5) MetaMask or similar Web3 provider for user interaction
6) A basic frontend application (HTML/JS/CSS) for user interface, though this could be developed separately
7) OpenZeppelin contracts for secure implementation patterns (optional)
### What are the potential risks or challenges in implementing this feature?
The potential risks and challenges include:
1) High gas costs making gameplay expensive if not optimized
2) Smart contract security vulnerabilities like reentrancy attacks or integer overflows
3) Poor user experience due to blockchain transaction delays
4) Abandoned games if players stop participating
5) Complexity in handling edge cases like ties or unexpected termination
6) Difficulties in upgrading the contract if bugs are found since blockchain code is immutable
7) Ensuring fairness in the game mechanics while maintaining decentralization
8) Testing challenges due to the distributed nature of blockchain applications
## Development Phases
### Phase 1: Smart Contract Development
**Status**: In Progress
**Description**: Develop the core Solidity smart contract for the Tic Tac Toe game, including game logic, state management, and event emission.
**Tasks**:
- Set up Hardhat development environment with Solidity 0.8.x
- Implement game board representation and state management
- Implement player registration and game creation functionality
- Implement move validation and game state updates
- Implement win condition detection and game completion logic
### Phase 2: Testing and Optimization
**Description**: Write test cases, optimize gas usage, and ensure security of the Tic Tac Toe contract.
**Tasks**:
- Write unit tests for all game functionality
- Perform gas optimization for core game functions
- Conduct security review and implement safeguards
### Phase 3: Deployment and Documentation
**Description**: Deploy the contract to testnets and create comprehensive documentation for developers and users.
**Tasks**:
- Deploy contract to Ethereum testnet (Goerli/Sepolia)
- Create technical documentation with API references
- Create a demo frontend for interacting with the contract
## Product Requirements Document
### 1. Introduction
#### 1.1 Purpose
This document outlines the requirements and specifications for a decentralized Tic Tac Toe game implemented as a Solidity smart contract on the Ethereum blockchain. The goal is to create a fully functional, gas-efficient, and secure implementation that demonstrates how traditional games can be implemented in a trustless, decentralized environment.
#### 1.2 Scope
The scope of this product includes the smart contract implementation of Tic Tac Toe, including game creation, player management, game logic, win condition detection, and wagering functionality. A basic web frontend for interacting with the contract will be developed as part of the demonstration but is not the primary focus of this PRD.
#### 1.3 Background
Blockchain games represent a growing segment of the web3 ecosystem, offering new possibilities for transparent and verifiable gameplay. Tic Tac Toe, as a simple yet widely understood game, provides an excellent introduction to smart contract gaming concepts while being straightforward enough to implement efficiently on-chain.
### 2. Product Overview
#### 2.1 Product Description
A decentralized Tic Tac Toe game built on Ethereum that allows two players to compete against each other with all game actions and state changes recorded on the blockchain. Players can create games, join existing games, make moves, and potentially wager ETH on the outcome.
#### 2.2 Target Users
- Blockchain enthusiasts interested in decentralized applications
- Ethereum developers learning smart contract development
- Educational platforms teaching blockchain concepts
- Casual players interested in crypto gaming experiences
### 3. Functional Requirements
#### 3.1 Game Creation and Setup
- Users must be able to create a new game, becoming player 1 (X)
- Users must be able to join an existing open game as player 2 (O)
- Game creators must be able to specify whether ETH wagering is enabled
- If wagering is enabled, both players must contribute the same amount of ETH to participate
#### 3.2 Gameplay Mechanics
- The game board must be represented as a 3x3 grid
- Players must take turns making moves, with player 1 (X) always going first
- The contract must validate moves to ensure they are made:
- By the correct player
- On a valid, empty position on the board
- During an active game
- The contract must prevent players from making moves when it's not their turn
- The contract must update and store the game state after each valid move
#### 3.3 Win Conditions and Game Completion
- The contract must detect win conditions: 3 in a row horizontally, vertically, or diagonally
- The contract must detect draw conditions when all positions are filled with no winner
- When a game is completed, the contract must:
- Record the winner (or draw)
- Prevent further moves
- Distribute any wagered ETH to the winner (or refund in case of a draw)
#### 3.4 Event Emission
- The contract must emit events for:
- Game creation
- Player joining a game
- Each valid move made
- Game completion (win/draw)
- ETH distribution if wagering is enabled
### 4. Non-Functional Requirements
#### 4.1 Performance and Optimization
- Gas usage for moves should be below 200,000 gas
- The contract should minimize on-chain storage to reduce gas costs
- The game logic should be optimized for minimal computational complexity
#### 4.2 Security
- The contract must implement proper access controls
- Input validation must be comprehensive to prevent unexpected game states
- The contract should be resistant to common smart contract vulnerabilities
- The contract must handle ETH transfers securely if wagering is enabled
#### 4.3 Compatibility
- The contract must be compatible with Solidity 0.8.x
- The contract must be deployable to Ethereum mainnet and testnets
- The contract should work with standard Web3 providers like MetaMask
### 5. Technical Specifications
#### 5.1 Smart Contract Architecture
- `TicTacToe.sol`: Main contract implementing the game logic
- Data structures:
- Game struct containing board state, player addresses, current turn, game status, and wager information
- Mapping from game ID to Game struct for multi-game support
- Key functions:
- `createGame()`: Create a new game instance
- `joinGame(uint gameId)`: Join an existing game
- `makeMove(uint gameId, uint8 x, uint8 y)`: Make a move on the board
- `getGameState(uint gameId)`: Return the current state of a specific game
#### 5.2 Development Environment
- Hardhat for development, testing, and deployment
- Solidity 0.8.x as the smart contract language
- Ethers.js for frontend integration
- OpenZeppelin contracts for security patterns (optional)
### 6. User Interface (Frontend)
While the frontend is not the primary focus, a basic web interface should be developed to demonstrate interaction with the smart contract:
#### 6.1 Key Frontend Features
- Connect wallet functionality
- Create new game / Join existing game options
- Visual representation of the game board
- Move selection interface
- Game status display
- Transaction status and confirmation
### 7. Testing Strategy
#### 7.1 Unit Testing
- Test all contract functions in isolation
- Verify win condition logic covers all possible winning configurations
- Test error conditions and invalid inputs
#### 7.2 Integration Testing
- Test full game scenarios from creation to completion
- Test wagering functionality if implemented
- Verify correct event emission
#### 7.3 Security Testing
- Review for common smart contract vulnerabilities
- Test for correct access control enforcement
- Verify proper handling of ETH transfers
### 8. Milestones and Implementation Plan
The implementation will be organized into three main phases:
#### 8.1 Phase 1: Smart Contract Development
- Set up development environment
- Implement core game logic and state management
- Build player registration and turn management
- Create win condition detection
#### 8.2 Phase 2: Testing and Optimization
- Develop comprehensive test suite
- Optimize for gas efficiency
- Conduct security review
#### 8.3 Phase 3: Deployment and Documentation
- Deploy to Ethereum testnet
- Create technical documentation
- Develop demo frontend
## Implementation Plan
### 1. Environment Setup
#### 1.1 Development Environment
- Set up a Hardhat project for Solidity development
- Configure for Solidity version 0.8.17
- Install necessary dependencies:
- `@openzeppelin/contracts` (optional, for security patterns)
- `@nomiclabs/hardhat-ethers` for testing
- `@nomiclabs/hardhat-waffle` for testing
- Configure testing environment with Hardhat
#### 1.2 Project Structure
```
/contracts
/TicTacToe.sol
/test
/TicTacToe.test.js
/scripts
/deploy.js
/frontend (optional for demo)
/src
/components
/utils
hardhat.config.js
package.json
README.md
```
### 2. Smart Contract Development
#### 2.1 Contract Data Structures
Define the core data structures:
```solidity
// Game status enum
enum GameStatus { OPEN, IN_PROGRESS, WINNER_X, WINNER_O, DRAW }
// Game struct to track game state
struct Game {
address playerX; // Player 1 (X)
address playerO; // Player 2 (O)
address currentTurn; // Whose turn it is
uint8[9] board; // Board state (0=empty, 1=X, 2=O)
GameStatus status; // Current game status
uint256 wagerAmount; // ETH wagered (if any)
uint256 createdAt; // Timestamp for game creation
}
// Mapping to track all games
mapping(uint256 => Game) public games;
uint256 public gameCount;
```
#### 2.2 Core Game Functions
Implement these core functions:
1. **Game Creation**
```solidity
function createGame(bool withWager) external payable returns (uint256 gameId) {
// Input validation for wager
// Create new game with player X as msg.sender
// Set initial game state
// Emit GameCreated event
}
```
2. **Joining a Game**
```solidity
function joinGame(uint256 gameId) external payable {
// Validate game exists and is open
// Validate wager amount if needed
// Set player O as msg.sender
// Update game status to IN_PROGRESS
// Emit PlayerJoined event
}
```
3. **Making a Move**
```solidity
function makeMove(uint256 gameId, uint8 position) external {
// Validate game state and player turn
// Validate move is legal (position is in range and empty)
// Update board state
// Check for win conditions
// Update game status if game is complete
// Handle ETH distribution if game is complete and has wager
// Emit MoveExecuted event
}
```
4. **Game State Retrieval**
```solidity
function getGameState(uint256 gameId) external view returns (
address playerX,
address playerO,
address currentTurn,
uint8[9] memory board,
GameStatus status
) {
// Return all relevant game state information
}
```
#### 2.3 Win Condition Detection
Implement an efficient algorithm to check for wins:
```solidity
function checkWinner(uint8[9] memory board) internal pure returns (bool hasWinner, uint8 winner) {
// Check rows, columns, and diagonals for 3 in a row
// Return winner (1 for X, 2 for O) if found
// Otherwise return no winner
}
```
#### 2.4 ETH Handling
Handle wagering functionality:
```solidity
function _distributeWinnings(Game storage game) internal {
// Send ETH to winner or refund in case of draw
// Handle potential transfer failures safely
}
```
### 3. Testing Strategy
#### 3.1 Unit Tests
Write tests for:
- Game creation with and without wager
- Joining games
- Making valid and invalid moves
- Win detection for all winning positions
- Draw detection
- ETH distribution logic
#### 3.2 Gas Optimization
- Use uint8 for board positions (0, 1, 2)
- Optimize win condition checking
- Minimize storage operations
- Consider using bit manipulation for board state
### 4. Deployment and Documentation
#### 4.1 Deployment Scripts
Create scripts for:
- Testnet deployment
- Local testing deployment
#### 4.2 Documentation
Document:
- Contract functions and parameters
- Game mechanics and flow
- Integration guidelines for frontends
- Examples of interaction using ethers.js
#### 4.3 Frontend Demo (Optional)
If time permits, create a basic React frontend:
- Wallet connection
- Game creation interface
- Game board visualization
- Move submission
### 5. Implementation Timeline
#### Week 1: Smart Contract Development
- Day 1-2: Set up environment and implement data structures
- Day 3-4: Implement core game functions
- Day 5: Implement win condition detection and ETH handling
#### Week 2: Testing and Optimization
- Day 1-2: Write comprehensive tests
- Day 3-4: Gas optimization
- Day 5: Security review
#### Week 3: Deployment and Documentation
- Day 1-2: Create deployment scripts and deploy to testnet
- Day 3-4: Write documentation
- Day 5: (Optional) Create basic frontend demo
================
File: src/templates/impl-template.md
================
# {{featureName}} Implementation Plan
## Overview
{{featureDescription}}
## Implementation Steps
{{#each phases}}
### Phase {{phaseNumber}}: {{phaseName}}
#### Objectives
{{objectives}}
#### Tasks
{{#each tasks}}
- [ ] {{description}}
{{/each}}
#### Code Style & Practices
{{codeStyle}}
{{/each}}
## File Structure
```
{{fileStructure}}
```
## Implementation Timeline
{{#each phases}}
{{phaseNumber}}. **{{phaseName}}**: {{timeEstimate}}
{{/each}}
## Next Steps
1. {{nextStep1}}
2. {{nextStep2}}
3. {{nextStep3}}
4. {{nextStep4}}
5. {{nextStep5}}
================
File: src/templates/prd-template.md
================
# {{featureName}} PRD
## 1. Introduction
{{featureDescription}}
## 2. Feature Objectives
{{objectives}}
## 3. Scope and Requirements
### 3.1 Feature Request Clarification
{{requirements}}
### 3.2 Technical Specifications
{{technicalSpecs}}
## 4. High-Level Implementation Overview
### 4.1 Development Workflow and Branching Strategy
- **Feature Branch:**
- Begin implementation on a dedicated branch named `feature/{{featureNameSlug}}`.
- **Phase Branches:**
- For each phase, create a branch off the feature branch named `phase/{{featureNameSlug}}/{{phaseNumber}}-{{phaseName}}`.
### 4.2 Implementation Phases
{{implementationPhases}}
## 5. Feedback and Iteration Process
- **User Feedback Integration:**
- Regularly incorporate user feedback to refine feature objectives and requirements.
- **Iterative Updates:**
- Update both the PRD and the implementation plan as new details emerge during the development process.
- **Review and Approval:**
- Ensure that each phase is reviewed and approved before moving to subsequent phases.
## 6. File Naming Conventions
- **PRD File:** `{{stepNumber}}_{{featureName}}_PRD.md`
- **Implementation Plan File:** `{{stepNumber}}_{{featureName}}_Implementation.md`
================
File: src/clarification.ts
================
/**
* Feature clarification module for the Vibe-Coder MCP Server.
* This module handles the iterative questioning to clarify feature requests.
*/
import { Feature, ClarificationResponse } from './types.js';
import { updateFeature, getFeature } from './storage.js';
import { now } from './utils.js';
/**
* Default questions to ask during feature clarification
*/
export const DEFAULT_CLARIFICATION_QUESTIONS = [
"What specific problem does this feature solve?",
"Who are the target users for this feature?",
"What are the key requirements for this feature?",
"What are the technical constraints or considerations?",
"How will we measure the success of this feature?",
"Are there any dependencies on other features or systems?",
"What are the potential risks or challenges in implementing this feature?"
];
/**
* Result when all clarification questions are complete
*/
export interface ClarificationComplete {
done: true;
message: string;
}
/**
* Get the next clarification question for a feature
* @param feature The feature to get the next question for
* @returns The next question to ask or a completion object if all questions have been answered
* @throws Error if the feature is missing the clarificationResponses array
*/
export function getNextClarificationQuestion(feature: Feature): string | ClarificationComplete {
if (!feature.clarificationResponses) {
// Throw a proper error instead of just logging
throw new Error(`Feature is missing clarificationResponses array: ${feature.id}`);
}
// Check if we've asked all the default questions
if (feature.clarificationResponses.length >= DEFAULT_CLARIFICATION_QUESTIONS.length) {
return {
done: true,
message: "All clarification questions have been answered. You can now generate a PRD for this feature."
};
}
// Get the next question based on the number of responses
return DEFAULT_CLARIFICATION_QUESTIONS[feature.clarificationResponses.length];
}
/**
* Add a clarification response to a feature
* @param featureId The ID of the feature to add the response to
* @param question The question that was asked
* @param answer The user's answer
* @returns The updated feature
* @throws Error if the feature is not found
*/
export function addClarificationResponse(
featureId: string,
question: string,
answer: string
): Feature {
const feature = getFeature(featureId);
if (!feature) {
throw new Error(`Feature with ID ${featureId} not found`);
}
// Create a new response
const newResponse: ClarificationResponse = {
question,
answer,
timestamp: now()
};
// Update the feature with the new response
const updatedFeature = updateFeature(featureId, {
clarificationResponses: [...feature.clarificationResponses, newResponse]
});
if (!updatedFeature) {
throw new Error(`Failed to update feature ${featureId} with new clarification response`);
}
return updatedFeature;
}
/**
* Format clarification responses as text
* @param responses The responses to format
* @returns Formatted text
*/
export function formatClarificationResponses(responses: ClarificationResponse[]): string {
if (!responses || responses.length === 0) {
return "No clarification responses yet.";
}
return responses.map(cr => `Q: ${cr.question}\nA: ${cr.answer}`).join('\n\n');
}
/**
* Check if a feature has completed the clarification process
* @param feature The feature to check
* @returns True if clarification is complete, false otherwise
* @throws Error if the feature is missing the clarificationResponses array
*/
export function isClarificationComplete(feature: Feature): boolean {
if (!feature.clarificationResponses) {
throw new Error(`Feature is missing clarificationResponses array: ${feature.id}`);
}
return feature.clarificationResponses.length >= DEFAULT_CLARIFICATION_QUESTIONS.length;
}
/**
* Get a summary of the clarification status
* @param feature The feature to get the status for
* @returns A text summary of the clarification status
* @throws Error if the feature is missing the clarificationResponses array
*/
export function getClarificationStatus(feature: Feature): string {
if (!feature.clarificationResponses) {
throw new Error(`Feature is missing clarificationResponses array: ${feature.id}`);
}
const total = DEFAULT_CLARIFICATION_QUESTIONS.length;
const completed = feature.clarificationResponses.length;
return `Clarification progress: ${completed}/${total} questions answered.`;
}
================
File: src/documentation.ts
================
/**
* Documentation generation functions for the Vibe-Coder MCP Server.
* This module handles generating PRDs and implementation plans from feature clarifications.
*/
import * as fs from 'fs';
import * as path from 'path';
import { Feature, ClarificationResponse, Phase } from './types.js';
import { formatDate } from './utils.js';
/**
* Load a template file and return its contents
* @param templateName The name of the template file (without the path)
* @returns The template content as a string
* @throws Error if the template cannot be loaded
*/
function loadTemplate(templateName: string): string {
try {
const templatePath = path.join(process.cwd(), 'src', 'templates', templateName);
return fs.readFileSync(templatePath, 'utf-8');
} catch (error) {
console.error(`Error loading template ${templateName}:`, error);
throw new Error(`Failed to load template ${templateName}: ${error instanceof Error ? error.message : String(error)}`);
}
}
/**
* Generate a PRD document from a feature and its clarification responses
* @param feature The feature to generate a PRD for
* @returns The generated PRD markdown content
*/
export function generatePRD(feature: Feature): string {
try {
const template = loadTemplate('prd-template.md');
// Replace template variables
return template
.replace(/{{featureName}}/g, feature.name)
.replace(/{{featureDescription}}/g, feature.description || '')
.replace(/{{featureNameSlug}}/g, slugify(feature.name))
.replace(/{{stepNumber}}/g, '01')
.replace(/{{objectives}}/g, extractObjectivesFromClarifications(feature.clarificationResponses))
.replace(/{{requirements}}/g, extractRequirementsFromClarifications(feature.clarificationResponses))
.replace(/{{technicalSpecs}}/g, extractTechnicalSpecsFromClarifications(feature.clarificationResponses))
.replace(/{{implementationPhases}}/g, generateImplementationPhasesList(feature));
} catch (error) {
console.warn(`Template loading failed, falling back to basic PRD: ${error instanceof Error ? error.message : String(error)}`);
return generateBasicPRD(feature);
}
}
/**
* Generate a basic PRD as fallback if template loading fails
* @param feature The feature to generate a PRD for
* @returns A basic PRD markdown content
*/
function generateBasicPRD(feature: Feature): string {
return `# ${feature.name} PRD
## 1. Introduction
${feature.description}
## 2. Feature Objectives
${extractObjectivesFromClarifications(feature.clarificationResponses)}
## 3. Scope and Requirements
${extractRequirementsFromClarifications(feature.clarificationResponses)}
## 4. Technical Specifications
${extractTechnicalSpecsFromClarifications(feature.clarificationResponses)}
## 5. Implementation Phases
${generateImplementationPhasesList(feature)}
## 6. Feedback and Iteration Process
This PRD will be updated as the implementation progresses and feedback is received.
`;
}
/**
* Generate an implementation plan from a feature and its clarification responses
* @param feature The feature to generate an implementation plan for
* @returns The generated implementation plan markdown content
*/
export function generateImplementationPlan(feature: Feature): string {
try {
const template = loadTemplate('implementation-plan-template.md');
// Replace template variables
return template
.replace(/{{featureName}}/g, feature.name)
.replace(/{{featureDescription}}/g, feature.description || '')
.replace(/{{featureNameSlug}}/g, slugify(feature.name))
.replace(/{{stepNumber}}/g, '02')
.replace(/{{objectives}}/g, extractObjectivesFromClarifications(feature.clarificationResponses))
.replace(/{{requirements}}/g, extractRequirementsFromClarifications(feature.clarificationResponses))
.replace(/{{technicalSpecs}}/g, extractTechnicalSpecsFromClarifications(feature.clarificationResponses))
.replace(/{{implementationPhases}}/g, generateImplementationPhasesList(feature))
.replace(/{{developmentPhases}}/g, generateDefaultPhases(feature).map(p => `## ${p.name}\n\n${p.description}`).join('\n\n'))
.replace(/{{fileStructure}}/g, generateFileStructure(feature))
.replace(/{{nextSteps}}/g, generateNextSteps(feature).map(step => `- ${step}`).join('\n'));
} catch (error) {
console.warn(`Template loading failed, falling back to basic implementation plan: ${error instanceof Error ? error.message : String(error)}`);
return generateBasicImplementationPlan(feature);
}
}
/**
* Generate a basic implementation plan as fallback if template loading fails
* @param feature The feature to generate an implementation plan for
* @returns A basic implementation plan markdown content
*/
function generateBasicImplementationPlan(feature: Feature): string {
const phases = generateDefaultPhases(feature);
let phasesContent = '';
phases.forEach((phase, index) => {
phasesContent += `\n### Phase ${index + 1}: ${phase.name}\n\n`;
phasesContent += `**Objectives**: ${phase.objectives}\n\n`;
phasesContent += `**Tasks**:\n`;
phase.tasks.forEach((task: string) => {
phasesContent += `- [ ] ${task}\n`;
});
phasesContent += `\n**Code Style & Practices**: ${phase.codeStyle}\n\n`;
});
return `# ${feature.name} Implementation Plan
## Overview
${feature.description}
## Implementation Steps
${phasesContent}
## File Structure
\`\`\`
${generateFileStructure(feature)}
\`\`\`
## Implementation Timeline
${phases.map((phase, i) => `${i + 1}. **${phase.name}**: ${phase.timeEstimate || '1-2 days'}`).join('\n')}
## Next Steps
${generateNextSteps(feature).map((step, i) => `${i + 1}. ${step}`).join('\n')}
`;
}
/**
* Extract objectives from clarification responses
* @param responses The clarification responses to extract objectives from
* @returns Markdown content for the objectives section
*/
export function extractObjectivesFromClarifications(responses: ClarificationResponse[]): string {
if (responses.length === 0) {
return "No objectives defined yet. Complete the clarification process to generate objectives.";
}
// Look for responses related to problems and users
const problemResponse = responses.find(r => r.question.includes("problem"));
const usersResponse = responses.find(r => r.question.includes("users"));
const successResponse = responses.find(r => r.question.includes("success"));
let objectives = "Based on the clarification responses, this feature aims to:\n\n";
if (problemResponse) {
objectives += `- **Solve a Problem**: ${problemResponse.answer}\n`;
}
if (usersResponse) {
objectives += `- **Target Users**: ${usersResponse.answer}\n`;
}
if (successResponse) {
objectives += `- **Success Criteria**: ${successResponse.answer}\n`;
}
objectives += "\nThe key objectives are to create a solution that is:\n";
objectives += "- Clean and maintainable\n";
objectives += "- Well-documented\n";
objectives += "- Follows best practices\n";
return objectives;
}
/**
* Extract requirements from clarification responses
* @param responses The clarification responses to extract requirements from
* @returns Markdown content for the requirements section
*/
export function extractRequirementsFromClarifications(responses: ClarificationResponse[]): string {
if (responses.length === 0) {
return "No requirements defined yet. Complete the clarification process to generate requirements.";
}
// Look for responses related to requirements
const requirementsResponse = responses.find(r => r.question.includes("requirements"));
const dependenciesResponse = responses.find(r => r.question.includes("dependencies"));
let requirements = "Based on the clarification responses, this feature requires:\n\n";
if (requirementsResponse) {
// Split the requirements by common delimiters and format as a list
const reqList = requirementsResponse.answer
.split(/[,.;]/)
.filter(item => item.trim().length > 0)
.map(item => `- ${item.trim()}`);
requirements += reqList.join('\n');
requirements += '\n\n';
}
if (dependenciesResponse) {
requirements += `**Dependencies**:\n${dependenciesResponse.answer}\n\n`;
}
return requirements;
}
/**
* Extract technical specifications from clarification responses
* @param responses The clarification responses to extract technical specifications from
* @returns Markdown content for the technical specifications section
*/
export function extractTechnicalSpecsFromClarifications(responses: ClarificationResponse[]): string {
if (responses.length === 0) {
return "No technical specifications defined yet. Complete the clarification process.";
}
// Look for responses related to technical constraints
const technicalResponse = responses.find(r => r.question.includes("technical constraints") || r.question.includes("considerations"));
const risksResponse = responses.find(r => r.question.includes("risks") || r.question.includes("challenges"));
let specs = "";
if (technicalResponse) {
specs += `**Technical Constraints**:\n${technicalResponse.answer}\n\n`;
}
if (risksResponse) {
specs += `**Potential Risks and Challenges**:\n${risksResponse.answer}\n\n`;
}
specs += `**Development Approach**:\n`;
specs += `- Use TypeScript for type safety\n`;
specs += `- Follow functional programming principles\n`;
specs += `- Implement thorough testing\n`;
specs += `- Use modular design\n`;
return specs;
}
/**
* Generate a list of implementation phases for the PRD
* @param feature The feature to generate phases for
* @returns Markdown content for the implementation phases section
*/
function generateImplementationPhasesList(feature: Feature): string {
const phases = generateDefaultPhases(feature);
let phasesList = "";
phases.forEach((phase, index) => {
phasesList += `**Phase ${index + 1}: ${phase.name}**\n`;
phasesList += `${phase.objectives}\n\n`;
});
return phasesList;
}
/**
* Generate default implementation phases based on the feature
* @param feature The feature to generate phases for
* @returns An array of phase objects
*/
function generateDefaultPhases(feature: Feature): any[] {
// If the feature already has phases defined, use those
if (feature.phases && feature.phases.length > 0) {
return feature.phases.map(phase => ({
name: phase.name,
objectives: phase.description,
tasks: phase.tasks.map(task => task.description),
codeStyle: "Follow TypeScript best practices, use functional programming where appropriate, and ensure thorough testing.",
timeEstimate: "1-2 days"
}));
}
// Otherwise, generate default phases
return [
{
name: "Requirements Analysis and Design",
objectives: "Analyze requirements, design the architecture, and create a detailed implementation plan.",
tasks: [
"Review and analyze clarification responses",
"Identify key components and their interactions",
"Design the system architecture",
"Create UML diagrams if necessary",
"Identify potential edge cases and risks"
],
codeStyle: "Create clear documentation with diagrams and detailed explanations.",
timeEstimate: "1-2 days"
},
{
name: "Core Implementation",
objectives: "Implement the core functionality based on the design.",
tasks: [
"Set up project structure and dependencies",
"Implement data models and interfaces",
"Build core business logic",
"Create unit tests for core functionality",
"Ensure code follows best practices"
],
codeStyle: "Use TypeScript with clear typing, follow functional programming principles, and use TDD where appropriate.",
timeEstimate: "2-3 days"
},
{
name: "Testing and Integration",
objectives: "Test all components, integrate with existing systems, and refine the implementation.",
tasks: [
"Write unit tests for all components",
"Perform integration testing",
"Fix bugs and edge cases",
"Optimize performance",
"Document any known limitations"
],
codeStyle: "Focus on test coverage and quality, fix edge cases, and document limitations.",
timeEstimate: "1-2 days"
},
{
name: "Documentation and Finalization",
objectives: "Finalize documentation, clean up code, and prepare for deployment.",
tasks: [
"Complete inline code documentation",
"Create user documentation",
"Clean up and refactor code",
"Prepare deployment strategy",
"Create final pull request"
],
codeStyle: "Ensure comprehensive documentation, clean code, and prepare for smooth deployment.",
timeEstimate: "1 day"
}
];
}
/**
* Generate a file structure based on the feature
* @param feature The feature to generate a file structure for
* @returns A string representation of the file structure
*/
function generateFileStructure(feature: Feature): string {
const featureNameSlug = slugify(feature.name);
return `src/
├── ${featureNameSlug}/
│ ├── index.ts # Main entry point
│ ├── types.ts # Type definitions
│ ├── components/ # UI components (if applicable)
│ │ └── index.ts
│ ├── hooks/ # Custom hooks (if applicable)
│ │ └── index.ts
│ ├── utils/ # Utility functions
│ │ └── index.ts
│ └── tests/ # Tests
│ └── index.test.ts
└── index.ts # Re-export public API`;
}
/**
* Generate next steps for implementing the feature
* @param feature The feature to generate next steps for
* @returns An array of next steps
*/
function generateNextSteps(feature: Feature): string[] {
return [
"Set up the project structure and dependencies",
"Implement core functionality based on the PRD",
"Write comprehensive tests for all components",
"Create clear documentation for users and developers",
"Prepare for code review and deployment"
];
}
/**
* Convert a string to a slug format
* @param str The string to convert
* @returns The slug version of the string
*/
function slugify(str: string): string {
return str
.toLowerCase()
.replace(/[^\w\s-]/g, '')
.replace(/[\s_-]+/g, '-')
.replace(/^-+|-+$/g, '');
}
================
File: src/errors.ts
================
/**
* @file errors.ts
* @version 1.0.0
*
* Provides standardized error handling utilities for the Vibe-Coder MCP Server.
* These utilities ensure consistent error responses following the JSON-RPC 2.0 specification.
*/
import { z } from 'zod';
// --------- Error Codes ---------
/**
* Standard JSON-RPC 2.0 error codes
* https://www.jsonrpc.org/specification#error_object
*/
export enum ErrorCode {
// JSON-RPC 2.0 Standard Error Codes
PARSE_ERROR = -32700,
INVALID_REQUEST = -32600,
METHOD_NOT_FOUND = -32601,
INVALID_PARAMS = -32602,
INTERNAL_ERROR = -32603,
// Custom Error Codes (must be between -32000 and -32099)
VALIDATION_ERROR = -32000,
RESOURCE_NOT_FOUND = -32001,
TOOL_NOT_FOUND = -32002,
PROMPT_NOT_FOUND = -32003,
UNAUTHORIZED = -32004,
FEATURE_NOT_FOUND = -32010,
PHASE_NOT_FOUND = -32011,
TASK_NOT_FOUND = -32012,
INVALID_PHASE_TRANSITION = -32013,
CLARIFICATION_INCOMPLETE = -32014,
}
// --------- Error Responses ---------
/**
* Standard JSON-RPC 2.0 error response structure
*/
export type ErrorResponse = {
error: {
code: ErrorCode;
message: string;
data?: any;
}
};
/**
* Tool error response
*/
export type ToolErrorResponse = {
content: [{
type: "text";
text: string;
}];
isError?: boolean;
};
/**
* Create a standard error response for JSON-RPC 2.0
*/
export const createErrorResponse = (
code: ErrorCode,
message: string,
data?: any
): ErrorResponse => {
return {
error: {
code,
message,
data
}
};
};
/**
* Create a tool error response
*/
export const createToolErrorResponse = (
message: string,
details?: any
): ToolErrorResponse => {
return {
content: [{
type: "text",
text: `Error: ${message}`
}],
isError: true
};
};
/**
* Capture and format Zod validation errors
*/
export const handleZodError = (error: z.ZodError): ErrorResponse => {
const formattedErrors = error.errors.map(err => ({
path: err.path.join('.'),
message: err.message
}));
return createErrorResponse(
ErrorCode.VALIDATION_ERROR,
"Validation error",
formattedErrors
);
};
/**
* Handle feature not found errors
*/
export const featureNotFoundError = (featureId: string): ToolErrorResponse => {
return createToolErrorResponse(`Feature with ID ${featureId} not found`);
};
/**
* Handle phase not found errors
*/
export const phaseNotFoundError = (
phaseId: string,
featureName: string
): ToolErrorResponse => {
return createToolErrorResponse(
`Phase with ID ${phaseId} not found in feature ${featureName}`
);
};
/**
* Handle task not found errors
*/
export const taskNotFoundError = (
taskId: string,
phaseName: string
): ToolErrorResponse => {
return createToolErrorResponse(
`Task with ID ${taskId} not found in phase ${phaseName}`
);
};
/**
* Handle invalid phase transition errors
*/
export const invalidPhaseTransitionError = (
currentStatus: string,
newStatus: string
): ToolErrorResponse => {
return createToolErrorResponse(
`Cannot transition phase from "${currentStatus}" to "${newStatus}"`
);
};
/**
* Handle clarification incomplete errors
*/
export const clarificationIncompleteError = (
status: any
): ToolErrorResponse => {
return createToolErrorResponse(
`Cannot proceed until clarification is complete`,
{ clarificationStatus: status }
);
};
/**
* Try-catch wrapper for Zod validation
*/
export const tryValidate = <T>(
schema: z.ZodType<T>,
data: unknown
): { success: true; data: T } | { success: false; error: ErrorResponse } => {
try {
return { success: true, data: schema.parse(data) };
} catch (error) {
if (error instanceof z.ZodError) {
return { success: false, error: handleZodError(error) };
}
return {
success: false,
error: createErrorResponse(
ErrorCode.INTERNAL_ERROR,
error instanceof Error ? error.message : "Unknown error"
)
};
}
};
================
File: src/index-updated.ts
================
#!/usr/bin/env node
/**
* @file Vibe-Coder MCP Server
* @version 0.2.0
*
* This MCP server implements a structured development workflow that helps
* LLM-based coders build features in an organized, clean, and safe manner.
*
* Core functionalities:
* - Feature request clarification through iterative questioning
* - PRD and implementation plan generation
* - Phased development with tasks and status tracking
*/
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListResourcesRequestSchema,
ListToolsRequestSchema,
ReadResourceRequestSchema,
ListPromptsRequestSchema,
GetPromptRequestSchema,
ResourceTemplate,
} from "@modelcontextprotocol/sdk/types.js";
// Import core modules
import { Feature, FeatureStorage, PhaseStatus, Phase, Task, ClarificationResponse } from './types.js';
import { features, storeFeature, getFeature, updateFeature, listFeatures } from './storage.js';
import {
DEFAULT_CLARIFICATION_QUESTIONS as CLARIFICATION_QUESTIONS,
getNextClarificationQuestion,
addClarificationResponse,
formatClarificationResponses,
isClarificationComplete,
getClarificationStatus
} from './clarification.js';
import { generatePRD, generateImplementationPlan } from './documentation.js';
import { createPhase, getPhase, updatePhaseStatus, getNextPhaseStatus, validatePhaseTransition, addTask, updateTaskStatus } from './phases.js';
import { generateId, createFeatureObject, createPhaseObject, createTaskObject, generateFeatureProgressSummary, isValidPhaseStatus } from './utils.js';
import { validateFeatureId, validatePhaseId, validateTaskId, validateFeaturePhaseTask, validateRequiredText, validatePhaseStatusValue } from './validators.js';
import { toolRegistry, resourceRegistry } from './registry.js';
import { registerToolHandlers } from './tool-handlers.js';
import { registerResourceHandlers } from './resource-handlers.js';
import { ErrorCode, createErrorResponse, createToolErrorResponse } from './errors.js';
/**
* Create an MCP server with capabilities for resources, tools, and prompts
*/
const server = new Server(
{
name: "Vibe-Coder MCP Server",
version: "0.2.0",
},
{
capabilities: {
resources: {}, // Expose resources for features, PRDs, and implementation plans
tools: {}, // Provide tools for feature clarification and development
prompts: {}, // Supply prompts for guiding the development process
},
}
);
/**
* Initialize the server by registering all tool and resource handlers
*/
function initializeServer() {
// Register all tool handlers
registerToolHandlers();
// Register all resource handlers
registerResourceHandlers();
console.error("Vibe-Coder MCP Server initialized successfully");
}
/**
* Handler for listing available resources.
*/
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: "features://list",
mimeType: "text/plain",
name: "Features List",
description: "Lists all features being developed"
},
{
uri: "features://status",
mimeType: "text/markdown",
name: "Project Status",
description: "Provides a summary of all features and their development status"
},
...listFeatures().flatMap(feature => [
{
uri: `feature://${feature.id}`,
mimeType: "text/plain",
name: feature.name,
description: `Details about feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/progress`,
mimeType: "text/markdown",
name: `${feature.name} Progress Report`,
description: `Detailed progress report for feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/prd`,
mimeType: "text/markdown",
name: `${feature.name} PRD`,
description: `PRD document for feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/implementation`,
mimeType: "text/markdown",
name: `${feature.name} Implementation Plan`,
description: `Implementation plan for feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/phases`,
mimeType: "text/plain",
name: `${feature.name} Phases`,
description: `Lists all phases for feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/tasks`,
mimeType: "text/plain",
name: `${feature.name} All Tasks`,
description: `Lists all tasks across all phases for feature: ${feature.name}`
},
...feature.phases.flatMap(phase => [
{
uri: `feature://${feature.id}/phase/${phase.id}`,
mimeType: "text/plain",
name: `${feature.name} - ${phase.name}`,
description: `Details about phase: ${phase.name} for feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/phase/${phase.id}/tasks`,
mimeType: "text/plain",
name: `${feature.name} - ${phase.name} Tasks`,
description: `Lists all tasks for phase: ${phase.name}`
},
...phase.tasks.map(task => ({
uri: `feature://${feature.id}/phase/${phase.id}/task/${task.id}`,
mimeType: "text/plain",
name: `Task: ${task.description.substring(0, 30)}${task.description.length > 30 ? '...' : ''}`,
description: `Details about task: ${task.description.substring(0, 50)}${task.description.length > 50 ? '...' : ''}`
}))
])
])
]
};
});
/**
* Handler for reading feature resources.
*/
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
try {
const uri = request.params.uri;
const match = resourceRegistry.findMatch(uri);
if (match) {
return await match.handler(new URL(uri), match.params);
}
return createErrorResponse(
ErrorCode.RESOURCE_NOT_FOUND,
`Resource not found: ${uri}`
);
} catch (error: any) {
console.error(`Error reading resource ${request.params.uri}:`, error);
return createErrorResponse(
ErrorCode.INTERNAL_ERROR,
error.message || 'Unknown error'
);
}
});
/**
* Handler that lists available tools.
*/
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: toolRegistry.listTools()
};
});
/**
* Handler for implementing MCP tools.
*/
server.setRequestHandler(CallToolRequestSchema, async (request) => {
try {
const toolName = request.params.name;
const toolArguments = request.params.arguments || {};
// Execute the tool using the tool registry
return await toolRegistry.execute(toolName, toolArguments);
} catch (error: any) {
console.error('Error executing tool:', error);
return createToolErrorResponse(`An unexpected error occurred: ${error.message || 'Unknown error'}`);
}
});
/**
* Handler that lists available prompts.
*/
server.setRequestHandler(ListPromptsRequestSchema, async () => {
return {
prompts: [
{
name: "clarify_feature",
description: "Guide to clarify a feature request through questioning"
}
]
};
});
/**
* Handler for the clarify_feature prompt.
*/
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
if (request.params.name === "clarify_feature") {
return {
messages: [
{
role: "user",
content: {
type: "text",
text: "Help me clarify this feature request by asking questions about:"
}
},
{
role: "user",
content: {
type: "text",
text: "1. The specific problem it solves\n2. The target users\n3. Key requirements\n4. Success criteria\n5. Technical constraints\n\nAsk one question at a time, analyze the response, then proceed to the next most relevant question."
}
}
]
};
}
return createErrorResponse(
ErrorCode.PROMPT_NOT_FOUND,
`Unknown prompt: ${request.params.name}`
);
});
/**
* Start the server using stdio transport.
*/
async function main() {
console.error("Starting Vibe-Coder MCP Server...");
// Initialize the server
initializeServer();
const transport = new StdioServerTransport();
await server.connect(transport);
}
main().catch((error) => {
console.error("Server error:", error);
process.exit(1);
});
================
File: src/index.ts
================
#!/usr/bin/env node
/**
* @file Vibe-Coder MCP Server
* @version 0.1.0
*
* This MCP server implements a structured development workflow that helps
* LLM-based coders build features in an organized, clean, and safe manner.
*
* Core functionalities:
* - Feature request clarification through iterative questioning
* - PRD and implementation plan generation
* - Phased development with tasks and status tracking
*/
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListResourcesRequestSchema,
ListToolsRequestSchema,
ReadResourceRequestSchema,
ListPromptsRequestSchema,
GetPromptRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
// Import core modules
import { Feature, FeatureStorage, PhaseStatus, Phase, Task, ClarificationResponse } from './types.js';
import { features, storeFeature, getFeature, updateFeature, listFeatures } from './storage.js';
import {
DEFAULT_CLARIFICATION_QUESTIONS as CLARIFICATION_QUESTIONS,
getNextClarificationQuestion,
addClarificationResponse,
formatClarificationResponses,
isClarificationComplete,
getClarificationStatus
} from './clarification.js';
import {
generatePRD,
generateImplementationPlan,
extractObjectivesFromClarifications,
extractRequirementsFromClarifications,
extractTechnicalSpecsFromClarifications
} from './documentation.js';
import {
createPhase,
getPhase,
updatePhaseStatus,
getNextPhaseStatus,
validatePhaseTransition,
addTask,
updateTaskStatus
} from './phases.js';
import {
generateId,
createFeatureObject,
createPhaseObject,
createTaskObject,
generateFeatureProgressSummary,
isValidPhaseStatus
} from './utils.js';
import { validateFeatureId, validatePhaseId, validateTaskId, validateFeaturePhaseTask, validateRequiredText, validatePhaseStatusValue } from './validators.js';
/**
* Type alias for a note object.
*/
type Note = { title: string, content: string };
/**
* Simple in-memory storage for notes.
* In a real implementation, this would likely be backed by a database.
*/
const notes: { [id: string]: Note } = {
"1": { title: "First Note", content: "This is note 1" },
"2": { title: "Second Note", content: "This is note 2" }
};
/**
* Create an MCP server with capabilities for resources, tools, and prompts
*/
const server = new Server(
{
name: "Vibe-Coder MCP Server",
version: "0.1.0",
},
{
capabilities: {
resources: {}, // Expose resources for features, PRDs, and implementation plans
tools: {}, // Provide tools for feature clarification and development
prompts: {}, // Supply prompts for guiding the development process
},
}
);
/**
* Handler for listing available resources.
* Exposes:
* - A list of all features
* - Individual feature details
* - PRD and implementation plan documents
* - Phase and task details
*/
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: "features://list",
mimeType: "text/plain",
name: "Features List",
description: "Lists all features being developed"
},
{
uri: "features://status",
mimeType: "text/markdown",
name: "Project Status",
description: "Provides a summary of all features and their development status"
},
...listFeatures().flatMap(feature => [
{
uri: `feature://${feature.id}`,
mimeType: "text/plain",
name: feature.name,
description: `Details about feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/progress`,
mimeType: "text/markdown",
name: `${feature.name} Progress Report`,
description: `Detailed progress report for feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/prd`,
mimeType: "text/markdown",
name: `${feature.name} PRD`,
description: `PRD document for feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/implementation`,
mimeType: "text/markdown",
name: `${feature.name} Implementation Plan`,
description: `Implementation plan for feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/phases`,
mimeType: "text/plain",
name: `${feature.name} Phases`,
description: `Lists all phases for feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/tasks`,
mimeType: "text/plain",
name: `${feature.name} All Tasks`,
description: `Lists all tasks across all phases for feature: ${feature.name}`
},
...feature.phases.flatMap(phase => [
{
uri: `feature://${feature.id}/phase/${phase.id}`,
mimeType: "text/plain",
name: `${feature.name} - ${phase.name}`,
description: `Details about phase: ${phase.name} for feature: ${feature.name}`
},
{
uri: `feature://${feature.id}/phase/${phase.id}/tasks`,
mimeType: "text/plain",
name: `${feature.name} - ${phase.name} Tasks`,
description: `Lists all tasks for phase: ${phase.name}`
},
...phase.tasks.map(task => ({
uri: `feature://${feature.id}/phase/${phase.id}/task/${task.id}`,
mimeType: "text/plain",
name: `Task: ${task.description.substring(0, 30)}${task.description.length > 30 ? '...' : ''}`,
description: `Details about task: ${task.description.substring(0, 50)}${task.description.length > 50 ? '...' : ''}`
}))
])
])
]
};
});
/**
* Handler for reading feature resources.
* Supports:
* - List of all features
* - Individual feature details
* - PRD and implementation plan documents
* - Phase and task details
*/
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
try {
const url = new URL(request.params.uri);
// Handle list of all features
if (url.protocol === "features:") {
if (url.pathname === "/list") {
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: listFeatures().map(f => `${f.id}: ${f.name}`).join("\n")
}]
};
}
if (url.pathname === "/status") {
const features = listFeatures();
if (features.length === 0) {
return {
contents: [{
uri: request.params.uri,
mimeType: "text/markdown",
text: "# Project Status\n\nNo features have been created yet."
}]
};
}
const featuresStatus = features.map(feature => {
const totalPhases = feature.phases.length;
const completedPhases = feature.phases.filter(p => p.status === 'completed' || p.status === 'reviewed').length;
const totalTasks = feature.phases.reduce((acc, phase) => acc + phase.tasks.length, 0);
const completedTasks = feature.phases.reduce(
(acc, phase) => acc + phase.tasks.filter(t => t.completed).length, 0
);
return `## ${feature.name}
- ID: ${feature.id}
- Status: ${completedPhases === totalPhases && totalPhases > 0 ? 'Completed' : 'In Progress'}
- Phases: ${completedPhases}/${totalPhases} completed
- Tasks: ${completedTasks}/${totalTasks} completed
- [View Details](feature://${feature.id}/progress)
`;
}).join('\n');
return {
contents: [{
uri: request.params.uri,
mimeType: "text/markdown",
text: `# Project Status\n\n${featuresStatus}`
}]
};
}
}
// Handle feature-specific resources
if (url.protocol === "feature:") {
// The hostname part is actually our feature ID in feature:// URLs
let featureId = "";
if (url.hostname) {
featureId = url.hostname;
} else {
// Try to get feature ID from pathname for backward compatibility
const parts = url.pathname.split('/').filter(Boolean);
if (parts.length > 0) {
featureId = parts[0];
}
}
if (!featureId) {
throw new Error(`Invalid feature URI: ${request.params.uri}. Missing feature ID.`);
}
const feature = getFeature(featureId);
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
// Extract path parts, excluding empty strings
const parts = url.pathname.split('/').filter(Boolean);
// Return feature details - no additional path parts beyond the feature ID
if (parts.length === 0) {
const timestamp = feature.updatedAt.toISOString();
const clarifications = formatClarificationResponses(feature.clarificationResponses);
const phasesText = feature.phases.map(p =>
`- ${p.name} (${p.status}): ${p.tasks.filter(t => t.completed).length}/${p.tasks.length} tasks completed`
).join('\n');
const featureDetails = `
Feature: ${feature.name}
ID: ${feature.id}
Description: ${feature.description}
Last Updated: ${timestamp}
Clarification Responses:
${clarifications}
Phases (${feature.phases.length}):
${phasesText}
`;
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: featureDetails
}]
};
}
// Resource is a sub-resource of the feature
if (parts.length >= 1) {
const subResource = parts[0];
// Return feature progress report
if (subResource === "progress") {
const progressReport = generateFeatureProgressSummary(feature);
return {
contents: [{
uri: request.params.uri,
mimeType: "text/markdown",
text: progressReport
}]
};
}
// Return PRD document
if (subResource === "prd") {
const prdContent = feature.prdDoc || generatePRD(feature);
return {
contents: [{
uri: request.params.uri,
mimeType: "text/markdown",
text: prdContent
}]
};
}
// Return implementation plan document
if (subResource === "implementation") {
const implContent = feature.implDoc || generateImplementationPlan(feature);
return {
contents: [{
uri: request.params.uri,
mimeType: "text/markdown",
text: implContent
}]
};
}
// Return phase listing
if (subResource === "phases") {
if (feature.phases.length === 0) {
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: `No phases defined for feature: ${feature.name}`
}]
};
}
const phasesContent = feature.phases.map(phase => {
const completedTasks = phase.tasks.filter(t => t.completed).length;
const totalTasks = phase.tasks.length;
return `Phase: ${phase.name} (ID: ${phase.id})
Status: ${phase.status}
Description: ${phase.description}
Progress: ${completedTasks}/${totalTasks} tasks completed
Last Updated: ${phase.updatedAt.toISOString()}
`;
}).join('\n---\n\n');
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: `# Phases for Feature: ${feature.name}\n\n${phasesContent}`
}]
};
}
// Handle list of all tasks for a feature
if (subResource === "tasks") {
const allTasks = feature.phases.flatMap(phase =>
phase.tasks.map(task => ({
...task,
phaseName: phase.name,
phaseId: phase.id,
phaseStatus: phase.status
}))
);
if (allTasks.length === 0) {
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: `No tasks defined for feature: ${feature.name}`
}]
};
}
const pendingTasks = allTasks.filter(t => !t.completed);
const completedTasks = allTasks.filter(t => t.completed);
const pendingTasksText = pendingTasks.length > 0
? pendingTasks.map(task => `- [ ] ${task.description} (ID: ${task.id}, Phase: ${task.phaseName})`).join('\n')
: "No pending tasks.";
const completedTasksText = completedTasks.length > 0
? completedTasks.map(task => `- [x] ${task.description} (ID: ${task.id}, Phase: ${task.phaseName})`).join('\n')
: "No completed tasks.";
const tasksContent = `# All Tasks for Feature: ${feature.name}
## Pending Tasks (${pendingTasks.length})
${pendingTasksText}
## Completed Tasks (${completedTasks.length})
${completedTasksText}
`;
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: tasksContent
}]
};
}
// Handle phase-specific resources
if (subResource === "phase" && parts.length >= 2) {
const phaseId = parts[1];
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
throw new Error(`Phase ${phaseId} not found in feature ${feature.name}`);
}
// Return phase details
if (parts.length === 2) {
const completedTasks = phase.tasks.filter(t => t.completed).length;
const totalTasks = phase.tasks.length;
const taskList = phase.tasks.map(task =>
`- [${task.completed ? 'x' : ' '}] ${task.description} (ID: ${task.id})`
).join('\n');
const phaseDetails = `
Phase: ${phase.name}
ID: ${phase.id}
Status: ${phase.status}
Description: ${phase.description}
Created: ${phase.createdAt.toISOString()}
Last Updated: ${phase.updatedAt.toISOString()}
Progress: ${completedTasks}/${totalTasks} tasks completed
Tasks:
${taskList}
`;
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: phaseDetails
}]
};
}
// Return task listing
if (parts[2] === "tasks") {
if (phase.tasks.length === 0) {
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: `No tasks defined for phase: ${phase.name}`
}]
};
}
const tasksContent = phase.tasks.map(task => `
Task: ${task.description}
ID: ${task.id}
Status: ${task.completed ? 'Completed' : 'Pending'}
Created: ${task.createdAt.toISOString()}
Last Updated: ${task.updatedAt.toISOString()}
`).join('\n---\n');
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: `# Tasks for Phase: ${phase.name}\n\n${tasksContent}`
}]
};
}
// Return individual task details
if (parts[2] === "task" && parts.length === 4) {
const taskId = parts[3];
const task = phase.tasks.find(t => t.id === taskId);
if (!task) {
throw new Error(`Task ${taskId} not found in phase ${phase.name}`);
}
const taskDetails = `
Task: ${task.description}
ID: ${task.id}
Status: ${task.completed ? 'Completed' : 'Pending'}
Created: ${task.createdAt.toISOString()}
Last Updated: ${task.updatedAt.toISOString()}
`;
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: taskDetails
}]
};
}
}
}
}
throw new Error(`Resource not found: ${request.params.uri}`);
} catch (error: any) {
console.error(`Error reading resource ${request.params.uri}:`, error);
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: `Error: ${error.message || 'Unknown error'}`
}]
};
}
});
/**
* Handler that lists available tools.
* Exposes tools for feature clarification and development.
*/
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: "start_feature_clarification",
description: "Start the clarification process for a new feature",
inputSchema: {
type: "object",
properties: {
featureName: {
type: "string",
description: "Name of the feature"
},
initialDescription: {
type: "string",
description: "Initial description of the feature"
}
},
required: ["featureName"],
examples: [
{
featureName: "User Authentication",
initialDescription: "Add login and registration functionality to the application"
},
{
featureName: "Data Export",
initialDescription: "Allow users to export their data in CSV and JSON formats"
}
]
}
},
{
name: "provide_clarification",
description: "Provide answer to a clarification question",
inputSchema: {
type: "object",
properties: {
featureId: {
type: "string",
description: "ID of the feature"
},
question: {
type: "string",
description: "Clarification question"
},
answer: {
type: "string",
description: "Answer to the clarification question"
}
},
required: ["featureId", "question", "answer"],
examples: [
{
featureId: "feature-123",
question: "What problem does this feature solve?",
answer: "This feature solves the problem of users forgetting their passwords by providing a secure password reset flow."
},
{
featureId: "feature-456",
question: "Who are the target users?",
answer: "The target users are administrators who need to manage user accounts and permissions."
}
]
}
},
{
name: "generate_prd",
description: "Generate a PRD document based on clarification responses",
inputSchema: {
type: "object",
properties: {
featureId: {
type: "string",
description: "ID of the feature"
}
},
required: ["featureId"],
examples: [
{
featureId: "feature-123"
}
]
},
handler: async (params: {featureId: string}) => {
const { featureId } = params;
const feature = getFeature(featureId);
if (!feature) {
return {
error: `Feature with ID ${featureId} not found`
};
}
if (!isClarificationComplete(feature)) {
return {
error: 'Cannot generate PRD until clarification is complete',
clarificationStatus: getClarificationStatus(feature)
};
}
// Generate the PRD
const prd = generatePRD(feature);
// Update the feature with the PRD
updateFeature(featureId, {
...feature,
prd,
updatedAt: new Date()
});
return {
success: true,
message: `PRD generated for feature ${feature.name}`,
prd
};
}
},
{
name: 'generate_implementation_plan',
description: 'Generate an implementation plan for a feature based on clarifications and PRD',
inputSchema: {
type: 'object',
properties: {
featureId: {
type: 'string',
description: 'The ID of the feature to generate an implementation plan for'
}
},
required: ['featureId']
},
handler: async (params: {featureId: string}) => {
const { featureId } = params;
const feature = getFeature(featureId);
if (!feature) {
return {
error: `Feature with ID ${featureId} not found`
};
}
if (!isClarificationComplete(feature)) {
return {
error: 'Cannot generate implementation plan until clarification is complete',
clarificationStatus: getClarificationStatus(feature)
};
}
// Generate the implementation plan
const implementationPlan = generateImplementationPlan(feature);
// Update the feature with the implementation plan
updateFeature(featureId, {
...feature,
implementationPlan,
updatedAt: new Date()
});
return {
success: true,
message: `Implementation plan generated for feature ${feature.name}`,
implementationPlan
};
}
},
{
name: 'create_phase',
description: 'Create a new development phase for a feature',
inputSchema: {
type: 'object',
properties: {
featureId: {
type: 'string',
description: 'ID of the feature to create a phase for'
},
name: {
type: 'string',
description: 'Name of the phase'
},
description: {
type: 'string',
description: 'Description of the phase'
}
},
required: ['featureId', 'name', 'description'],
examples: [
{
featureId: "feature-123",
name: "Requirements Analysis",
description: "Gather and analyze requirements for the feature"
},
{
featureId: "feature-123",
name: "Implementation",
description: "Implement the core functionality of the feature"
}
]
},
handler: async (params: {featureId: string, name: string, description: string}) => {
const { featureId, name, description } = params;
const feature = getFeature(featureId);
if (!feature) {
return {
error: `Feature with ID ${featureId} not found`
};
}
// Create the phase with validated inputs
const phaseId = generateId();
const phase = createPhase(feature.id, name, description);
return {
success: true,
message: `Phase ${name} created for feature ${feature.name}`,
phase
};
}
},
{
name: 'update_phase_status',
description: 'Update the status of a development phase',
inputSchema: {
type: 'object',
properties: {
featureId: {
type: 'string',
description: 'ID of the feature containing the phase'
},
phaseId: {
type: 'string',
description: 'ID of the phase to update'
},
status: {
type: 'string',
description: 'New status for the phase (pending, in_progress, completed, reviewed)'
}
},
required: ['featureId', 'phaseId', 'status'],
examples: [
{
featureId: "feature-123",
phaseId: "phase-456",
status: "in_progress"
},
{
featureId: "feature-123",
phaseId: "phase-456",
status: "completed"
}
]
},
handler: async (params: {featureId: string, phaseId: string, status: PhaseStatus}) => {
const { featureId, phaseId, status } = params;
const feature = getFeature(featureId);
if (!feature) {
return {
error: `Feature with ID ${featureId} not found`
};
}
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
return {
error: `Phase with ID ${phaseId} not found in feature ${feature.name}`
};
}
// Validate the status transition
const validationResult = validatePhaseTransition(phase.status, status);
if (!validationResult.valid) {
return {
error: validationResult.message
};
}
// Update the phase status
const updatedPhase = updatePhaseStatus(featureId, phaseId, status);
return {
success: true,
message: `Phase ${phase.name} status updated to ${status}`,
phase: updatedPhase
};
}
},
{
name: 'add_task',
description: 'Add a task to a development phase',
inputSchema: {
type: 'object',
properties: {
featureId: {
type: 'string',
description: 'ID of the feature containing the phase'
},
phaseId: {
type: 'string',
description: 'ID of the phase to add the task to'
},
description: {
type: 'string',
description: 'Description of the task'
}
},
required: ['featureId', 'phaseId', 'description'],
examples: [
{
featureId: "feature-123",
phaseId: "phase-456",
description: "Create database migration scripts"
},
{
featureId: "feature-123",
phaseId: "phase-456",
description: "Implement user interface components"
}
]
},
handler: async (params: {featureId: string, phaseId: string, description: string}) => {
const { featureId, phaseId, description } = params;
const feature = getFeature(featureId);
if (!feature) {
return {
error: `Feature with ID ${featureId} not found`
};
}
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
return {
error: `Phase with ID ${phaseId} not found in feature ${feature.name}`
};
}
// Add the task to the phase
const updatedPhase = addTask(featureId, phaseId, description);
return {
success: true,
message: `Task added to phase ${phase.name}`,
phase: updatedPhase
};
}
},
{
name: 'update_task_status',
description: 'Update the completion status of a task',
inputSchema: {
type: 'object',
properties: {
featureId: {
type: 'string',
description: 'ID of the feature containing the phase'
},
phaseId: {
type: 'string',
description: 'ID of the phase containing the task'
},
taskId: {
type: 'string',
description: 'ID of the task to update'
},
completed: {
type: 'boolean',
description: 'Whether the task is completed'
}
},
required: ['featureId', 'phaseId', 'taskId', 'completed'],
examples: [
{
featureId: "feature-123",
phaseId: "phase-456",
taskId: "task-789",
completed: true
},
{
featureId: "feature-123",
phaseId: "phase-456",
taskId: "task-789",
completed: false
}
]
},
handler: async (params: {featureId: string, phaseId: string, taskId: string, completed: boolean}) => {
const { featureId, phaseId, taskId, completed } = params;
const feature = getFeature(featureId);
if (!feature) {
return {
error: `Feature with ID ${featureId} not found`
};
}
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
return {
error: `Phase with ID ${phaseId} not found in feature ${feature.name}`
};
}
const task = phase.tasks.find(t => t.id === taskId);
if (!task) {
return {
error: `Task with ID ${taskId} not found in phase ${phase.name}`
};
}
// Update the task status
const updatedTask = updateTaskStatus(featureId, phaseId, taskId, completed);
// Check if all tasks are completed and suggest phase update if applicable
let message = `Task status updated to ${completed ? 'completed' : 'not completed'}`;
// @ts-ignore - We know the task structure from our validation
if (completed && phase.tasks.every(t => t.id === taskId || t.completed)) {
// All tasks are now completed
message += `. All tasks in phase ${phase.name} are now completed. Consider updating the phase status to 'completed'.`;
}
return {
success: true,
message,
task: updatedTask
};
}
},
{
name: 'get_next_phase_action',
description: 'Get guidance on what to do next in the current phase or whether to move to the next phase',
inputSchema: {
type: 'object',
properties: {
featureId: {
type: 'string',
description: 'ID of the feature'
}
},
required: ['featureId'],
examples: [
{
featureId: "feature-123"
}
]
},
handler: async (params: {featureId: string}) => {
const { featureId } = params;
const feature = getFeature(featureId);
if (!feature) {
return {
error: `Feature with ID ${featureId} not found`
};
}
// Find the current active phase (first non-completed/reviewed phase)
// @ts-ignore - We know the phase structure from our Feature type
const currentPhase = feature.phases.find(p => p.status === 'pending' || p.status === 'in_progress');
if (!currentPhase) {
// All phases are completed or reviewed
return {
content: [{
type: "text",
text: 'All phases are completed or reviewed. The feature implementation is done!'
}]
};
}
// Check task completion status
// @ts-ignore - We know the task structure from our Phase type
const completedTasks = currentPhase.tasks.filter(t => t.completed);
// @ts-ignore - We know the task structure from our Phase type
const pendingTasks = currentPhase.tasks.filter(t => !t.completed);
// Determine next action based on phase and task status
let message = '';
if (currentPhase.status === 'pending') {
message = `Phase "${currentPhase.name}" is pending. Start working on this phase by setting its status to "in_progress".`;
} else if (currentPhase.status === 'in_progress') {
if (pendingTasks.length > 0) {
message = `${completedTasks.length}/${currentPhase.tasks.length} tasks are completed in phase "${currentPhase.name}". Continue working on pending tasks.`;
} else if (currentPhase.tasks.length === 0) {
message = `Phase "${currentPhase.name}" has no tasks defined. Add tasks or mark the phase as completed if appropriate.`;
} else {
// All tasks are completed
message = `All tasks in phase "${currentPhase.name}" are completed. Consider marking this phase as completed.`;
}
}
return {
content: [{
type: "text",
text: message
}]
};
}
}
]
};
});
/**
* Handler for implementing MCP tools.
* Handles feature clarification, PRD generation, and more.
*/
server.setRequestHandler(CallToolRequestSchema, async (request) => {
try {
switch (request.params.name) {
case "start_feature_clarification": {
const featureName = String(request.params.arguments?.featureName || "");
const initialDescription = String(request.params.arguments?.initialDescription || "");
// Validate inputs
const nameValidation = validateRequiredText(featureName, "Feature name", 2, 100);
if (!nameValidation.valid) {
return {
content: [{
type: "text",
text: `Error: ${nameValidation.message}`
}]
};
}
// Initial description is optional, but if provided, validate its length
if (initialDescription && initialDescription.trim() !== "") {
const descValidation = validateRequiredText(initialDescription, "Initial description", 1, 5000);
if (!descValidation.valid) {
return {
content: [{
type: "text",
text: `Error: ${descValidation.message}`
}]
};
}
}
// Create a new feature
const feature = createFeatureObject(nameValidation.data, initialDescription);
storeFeature(feature);
// Get the first clarification question
const firstQuestion = getNextClarificationQuestion(feature);
return {
content: [{
type: "text",
text: `Feature ID: ${feature.id}\n\nLet's clarify your feature request. ${firstQuestion}`
}]
};
}
case "provide_clarification": {
const featureId = String(request.params.arguments?.featureId || "");
const question = String(request.params.arguments?.question || "");
const answer = String(request.params.arguments?.answer || "");
console.log(`\n[CLARIFICATION] Received request for feature ${featureId}\n Question: "${question.substring(0, 50)}..."\n Answer: "${answer.substring(0, 50)}..."`);
// Basic validation
if (!featureId || !answer) {
console.log(`[CLARIFICATION] Missing required fields: featureId=${!!featureId}, answer=${!!answer}`);
return {
content: [{
type: "text",
text: "Error: Feature ID and answer are required"
}]
};
}
// Get the feature
const feature = getFeature(featureId);
if (!feature) {
console.log(`[CLARIFICATION] Feature ID ${featureId} not found`);
return {
content: [{
type: "text",
text: `Error: Feature with ID ${featureId} not found`
}]
};
}
console.log(`[CLARIFICATION] Found feature: ${feature.name} with ${feature.clarificationResponses.length} existing responses`);
// Add the clarification response to the feature
feature.clarificationResponses.push({
question,
answer,
timestamp: new Date()
});
console.log(`[CLARIFICATION] Added response, now has ${feature.clarificationResponses.length} responses`);
// Save the feature with the updated clarification response
updateFeature(featureId, feature);
// Determine which question to ask next
const nextQuestionIndex = feature.clarificationResponses.length;
console.log(`[CLARIFICATION] Next question index would be: ${nextQuestionIndex}`);
console.log(`[CLARIFICATION] Total questions available: ${CLARIFICATION_QUESTIONS.length}`);
if (nextQuestionIndex < CLARIFICATION_QUESTIONS.length) {
// We have more questions to ask
const nextQuestion = CLARIFICATION_QUESTIONS[nextQuestionIndex];
console.log(`[CLARIFICATION] Returning next question: "${nextQuestion.substring(0, 50)}..."`);
return {
content: [{
type: "text",
text: `Response recorded. ${nextQuestion}`
}]
};
} else {
// All questions answered
console.log(`[CLARIFICATION] All questions answered`);
return {
content: [{
type: "text",
text: "All clarification questions have been answered. You can now generate a PRD for this feature."
}]
};
}
}
case "generate_prd": {
const featureId = String(request.params.arguments?.featureId || "");
// Validate feature ID
const featureResult = validateFeatureId(featureId);
if (!featureResult.valid) {
return {
content: [{
type: "text",
text: `Error: ${featureResult.message}`
}]
};
}
const feature = featureResult.data;
// Check if clarifications are complete
if (!isClarificationComplete(feature)) {
return {
content: [{
type: "text",
text: "Error: Please complete all clarification questions before generating a PRD."
}]
};
}
// Generate PRD and implementation plan
const prdDoc = generatePRD(feature);
const implementationPlan = generateImplementationPlan(feature);
// Store the documents
feature.prdDoc = prdDoc;
feature.implementationPlan = implementationPlan;
return {
content: [{
type: "text",
text: `PRD and Implementation Plan generated for feature ${feature.name}. You can view them using the resource URIs: feature://${feature.id}/prd and feature://${feature.id}/implementation`
}]
};
}
case "create_phase": {
const featureId = String(request.params.arguments?.featureId || "");
const phaseName = String(request.params.arguments?.name || "");
const phaseDescription = String(request.params.arguments?.description || "");
const tasksJson = String(request.params.arguments?.tasks || "[]");
// Validate feature ID
const featureResult = validateFeatureId(featureId);
if (!featureResult.valid) {
return {
content: [{
type: "text",
text: `Error: ${featureResult.message}`
}]
};
}
// Validate phase name
const nameValidation = validateRequiredText(phaseName, "Phase name", 2, 100);
if (!nameValidation.valid) {
return {
content: [{
type: "text",
text: `Error: ${nameValidation.message}`
}]
};
}
// Validate phase description (optional but if provided, validate)
if (phaseDescription && phaseDescription.trim() !== "") {
const descValidation = validateRequiredText(phaseDescription, "Phase description", 5, 1000);
if (!descValidation.valid) {
return {
content: [{
type: "text",
text: `Error: ${descValidation.message}`
}]
};
}
}
// Parse and validate tasks
let tasks = [];
try {
tasks = JSON.parse(tasksJson);
if (!Array.isArray(tasks)) {
return {
content: [{
type: "text",
text: "Error: Tasks must be a valid JSON array of task descriptions"
}]
};
}
// Validate each task description
for (let i = 0; i < tasks.length; i++) {
const taskDesc = tasks[i];
if (typeof taskDesc !== 'string' || taskDesc.trim().length < 3) {
return {
content: [{
type: "text",
text: `Error: Task at index ${i} must be a string with at least 3 characters`
}]
};
}
}
} catch (e) {
return {
content: [{
type: "text",
text: "Error: Could not parse tasks JSON. Please provide a valid JSON array."
}]
};
}
const feature = featureResult.data;
// Create the phase
const phase = createPhase(featureId, nameValidation.data, phaseDescription);
if (!phase) {
return {
content: [{
type: "text",
text: `Error: Failed to create phase for feature ${feature.name}`
}]
};
}
// Add tasks if provided
if (tasks.length > 0) {
tasks.forEach(taskDesc => {
addTask(featureId, phase.id, taskDesc);
});
}
return {
content: [{
type: "text",
text: `Phase "${phaseName}" created with ID: ${phase.id}`
}]
};
}
case "update_phase_status": {
const featureId = String(request.params.arguments?.featureId || "");
const phaseId = String(request.params.arguments?.phaseId || "");
const status = String(request.params.arguments?.status || "");
// Validate feature and phase
const validationResult = validateFeaturePhaseTask(featureId, phaseId);
if (!validationResult.valid) {
return {
content: [{
type: "text",
text: `Error: ${validationResult.message}`
}]
};
}
// Validate status
const statusValidation = validatePhaseStatusValue(status);
if (!statusValidation.valid) {
return {
content: [{
type: "text",
text: `Error: ${statusValidation.message}`
}]
};
}
const { feature, phase } = validationResult.data;
// Update the phase status
const updatedPhase = updatePhaseStatus(featureId, phaseId, statusValidation.data);
return {
content: [{
type: "text",
text: `Phase status updated to "${status}"`
}]
};
}
case "add_task": {
const featureId = String(request.params.arguments?.featureId || "");
const phaseId = String(request.params.arguments?.phaseId || "");
const taskDescription = String(request.params.arguments?.description || "");
// Validate feature and phase
const validationResult = validateFeaturePhaseTask(featureId, phaseId);
if (!validationResult.valid) {
return {
content: [{
type: "text",
text: `Error: ${validationResult.message}`
}]
};
}
// Validate task description
const descValidation = validateRequiredText(taskDescription, "Task description", 3, 500);
if (!descValidation.valid) {
return {
content: [{
type: "text",
text: `Error: ${descValidation.message}`
}]
};
}
const { feature, phase } = validationResult.data;
// Add the task
const taskId = addTask(featureId, phaseId, descValidation.data);
return {
content: [{
type: "text",
text: `Task added to phase "${phase.name}" with ID: ${taskId}`
}]
};
}
case "update_task_status": {
const featureId = String(request.params.arguments?.featureId || "");
const phaseId = String(request.params.arguments?.phaseId || "");
const taskId = String(request.params.arguments?.taskId || "");
const completed = Boolean(request.params.arguments?.completed);
// Validate feature, phase and task
const validationResult = validateFeaturePhaseTask(featureId, phaseId, taskId);
if (!validationResult.valid) {
return {
content: [{
type: "text",
text: `Error: ${validationResult.message}`
}]
};
}
const { feature, phase, task } = validationResult.data;
// Update the task status
const updatedTask = updateTaskStatus(featureId, phaseId, taskId, completed);
// Check if all tasks are completed and suggest phase update if applicable
let message = `Task status updated to ${completed ? 'completed' : 'not completed'}`;
// @ts-ignore - We know the task structure from our validation
if (completed && phase.tasks.every(t => t.id === taskId || t.completed)) {
// All tasks are now completed
message += `. All tasks in phase ${phase.name} are now completed. Consider updating the phase status to 'completed'.`;
}
return {
content: [{
type: "text",
text: message
}]
};
}
case "get_next_phase_action": {
const featureId = String(request.params.arguments?.featureId || "");
// Validate feature ID
const featureResult = validateFeatureId(featureId);
if (!featureResult.valid) {
return {
content: [{
type: "text",
text: `Error: ${featureResult.message}`
}]
};
}
const feature = featureResult.data;
// Find the current active phase (first non-completed/reviewed phase)
// @ts-ignore - We know the phase structure from our Feature type
const currentPhase = feature.phases.find(p => p.status === 'pending' || p.status === 'in_progress');
if (!currentPhase) {
// All phases are completed or reviewed
return {
content: [{
type: "text",
text: 'All phases are completed or reviewed. The feature implementation is done!'
}]
};
}
// Check task completion status
// @ts-ignore - We know the task structure from our Phase type
const completedTasks = currentPhase.tasks.filter(t => t.completed);
// @ts-ignore - We know the task structure from our Phase type
const pendingTasks = currentPhase.tasks.filter(t => !t.completed);
// Determine next action based on phase and task status
let message = '';
if (currentPhase.status === 'pending') {
message = `Phase "${currentPhase.name}" is pending. Start working on this phase by setting its status to "in_progress".`;
} else if (currentPhase.status === 'in_progress') {
if (pendingTasks.length > 0) {
message = `${completedTasks.length}/${currentPhase.tasks.length} tasks are completed in phase "${currentPhase.name}". Continue working on pending tasks.`;
} else if (currentPhase.tasks.length === 0) {
message = `Phase "${currentPhase.name}" has no tasks defined. Add tasks or mark the phase as completed if appropriate.`;
} else {
// All tasks are completed
message = `All tasks in phase "${currentPhase.name}" are completed. Consider marking this phase as completed.`;
}
}
return {
content: [{
type: "text",
text: message
}]
};
}
default:
return {
content: [{
type: "text",
text: `Error: Unknown tool "${request.params.name}"`
}]
};
}
} catch (error: any) {
console.error('Error executing tool:', error);
return {
content: [{
type: "text",
text: `An unexpected error occurred: ${error.message || 'Unknown error'}`
}]
};
}
});
/**
* Handler that lists available prompts.
*/
server.setRequestHandler(ListPromptsRequestSchema, async () => {
return {
prompts: [
{
name: "clarify_feature",
description: "Guide to clarify a feature request through questioning"
}
]
};
});
/**
* Handler for the clarify_feature prompt.
* Returns a prompt that guides feature clarification.
*/
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
if (request.params.name === "clarify_feature") {
return {
messages: [
{
role: "user",
content: {
type: "text",
text: "Help me clarify this feature request by asking questions about:"
}
},
{
role: "user",
content: {
type: "text",
text: "1. The specific problem it solves\n2. The target users\n3. Key requirements\n4. Success criteria\n5. Technical constraints\n\nAsk one question at a time, analyze the response, then proceed to the next most relevant question."
}
}
]
};
}
throw new Error("Unknown prompt");
});
/**
* Start the server using stdio transport.
* This allows the server to communicate via standard input/output streams.
*/
async function main() {
console.error("Starting Vibe-Coder MCP Server...");
const transport = new StdioServerTransport();
await server.connect(transport);
}
main().catch((error) => {
console.error("Server error:", error);
process.exit(1);
});
================
File: src/mcp-server.ts
================
#!/usr/bin/env node
/**
* @file Vibe-Coder MCP Server
* @version 0.3.0
* @status STABLE - DO NOT MODIFY WITHOUT TESTS
* @lastModified 2023-03-23
*
* This MCP server implements a structured development workflow that helps
* LLM-based coders build features in an organized, clean, and safe manner.
*
* IMPORTANT:
* - Test any modifications thoroughly
* - Maintain backward compatibility
*
* Functionality:
* - Feature request clarification through iterative questioning
* - PRD and implementation plan generation
* - Phased development with tasks and status tracking
*/
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
// Import core modules
import { Feature, Phase, Task, ClarificationResponse, PhaseStatus } from './types.js';
import { getFeature, updateFeature, listFeatures } from './storage.js';
import {
getNextClarificationQuestion,
addClarificationResponse,
formatClarificationResponses,
isClarificationComplete
} from './clarification.js';
import { generatePRD, generateImplementationPlan } from './documentation.js';
import { createFeatureObject, generateFeatureProgressSummary, createPhaseObject, createTaskObject, now } from './utils.js';
/**
* Create an MCP server
*/
const server = new McpServer({
name: "Vibe-Coder",
version: "0.3.0"
});
// --------- Helper Functions ---------
/**
* Create a new phase for a feature directly
*/
function createPhaseDirectly(feature: Feature, name: string, description: string): Phase {
const newPhase = createPhaseObject(name, description);
feature.phases.push(newPhase);
feature.updatedAt = new Date();
return newPhase;
}
/**
* Update phase status directly
*/
function updatePhaseStatusDirectly(feature: Feature, phaseId: string, status: PhaseStatus): void {
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
throw new Error(`Phase ${phaseId} not found`);
}
phase.status = status;
phase.updatedAt = now();
feature.updatedAt = now();
}
/**
* Add task directly
*/
function addTaskDirectly(feature: Feature, phaseId: string, description: string): Task {
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
throw new Error(`Phase ${phaseId} not found`);
}
const newTask = createTaskObject(description);
// Convert task ID to string to ensure it's not an object
if (typeof newTask.id !== 'string') {
newTask.id = String(newTask.id);
}
phase.tasks.push(newTask);
phase.updatedAt = now();
feature.updatedAt = now();
return newTask;
}
/**
* Update task status directly
*/
function updateTaskStatusDirectly(feature: Feature, phaseId: string, taskId: string, completed: boolean): void {
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
throw new Error(`Phase ${phaseId} not found`);
}
const task = phase.tasks.find(t => t.id === taskId);
if (!task) {
throw new Error(`Task ${taskId} not found`);
}
task.completed = completed;
task.updatedAt = now();
phase.updatedAt = now();
feature.updatedAt = now();
}
// --------- Register Resources ---------
// Features list resource
server.resource(
"features-list",
"features://list",
async (uri) => ({
contents: [{
uri: uri.href,
text: listFeatures().map(f => `${f.id}: ${f.name}`).join("\n")
}]
})
);
// Features status resource
server.resource(
"features-status",
"features://status",
async (uri) => {
const features = listFeatures();
if (features.length === 0) {
return {
contents: [{
uri: uri.href,
text: "# Project Status\n\nNo features have been created yet."
}]
};
}
const featuresStatus = features.map(feature => {
const totalPhases = feature.phases.length;
const completedPhases = feature.phases.filter(p => p.status === 'completed' || p.status === 'reviewed').length;
const totalTasks = feature.phases.reduce((acc, phase) => acc + phase.tasks.length, 0);
const completedTasks = feature.phases.reduce(
(acc, phase) => acc + phase.tasks.filter(t => t.completed).length, 0
);
return `## ${feature.name}
- ID: ${feature.id}
- Status: ${completedPhases === totalPhases && totalPhases > 0 ? 'Completed' : 'In Progress'}
- Phases: ${completedPhases}/${totalPhases} completed
- Tasks: ${completedTasks}/${totalTasks} completed
- [View Details](feature://${feature.id}/progress)
`;
}).join('\n');
return {
contents: [{
uri: uri.href,
text: `# Project Status\n\n${featuresStatus}`
}]
};
}
);
// Feature detail resource with parameter
server.resource(
"feature-detail",
new ResourceTemplate("feature://{featureId}", { list: undefined }),
async (uri, { featureId }) => {
const feature = getFeature(featureId as string);
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
const timestamp = feature.updatedAt.toISOString();
const clarifications = formatClarificationResponses(feature.clarificationResponses);
const phasesText = feature.phases.map(p =>
`- ${p.name} (${p.status}): ${p.tasks.filter(t => t.completed).length}/${p.tasks.length} tasks completed`
).join('\n');
const featureDetails = `
Feature: ${feature.name}
ID: ${feature.id}
Description: ${feature.description}
Last Updated: ${timestamp}
Clarification Responses:
${clarifications}
Phases (${feature.phases.length}):
${phasesText}
`;
return {
contents: [{
uri: uri.href,
text: featureDetails
}]
};
}
);
// Feature progress resource
server.resource(
"feature-progress",
new ResourceTemplate("feature://{featureId}/progress", { list: undefined }),
async (uri, { featureId }) => {
const feature = getFeature(featureId as string);
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
const progressReport = generateFeatureProgressSummary(feature);
return {
contents: [{
uri: uri.href,
text: progressReport
}]
};
}
);
// Feature PRD resource
server.resource(
"feature-prd",
new ResourceTemplate("feature://{featureId}/prd", { list: undefined }),
async (uri, { featureId }) => {
const feature = getFeature(featureId as string);
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
if (!isClarificationComplete(feature)) {
return {
contents: [{
uri: uri.href,
text: "# PRD Not Available\n\nThe clarification process is not complete. Please answer all clarification questions first."
}]
};
}
const prd = generatePRD(feature);
return {
contents: [{
uri: uri.href,
text: prd
}]
};
}
);
// Feature implementation plan resource
server.resource(
"feature-implementation-plan",
new ResourceTemplate("feature://{featureId}/implementation", { list: undefined }),
async (uri, { featureId }) => {
const feature = getFeature(featureId as string);
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
if (!isClarificationComplete(feature)) {
return {
contents: [{
uri: uri.href,
text: "# Implementation Plan Not Available\n\nThe clarification process is not complete. Please answer all clarification questions first."
}]
};
}
const implementationPlan = generateImplementationPlan(feature);
return {
contents: [{
uri: uri.href,
text: implementationPlan
}]
};
}
);
// --------- Register Tools ---------
// Start feature clarification tool
server.tool(
"start_feature_clarification",
{
featureName: z.string().min(2).max(100),
initialDescription: z.string().optional().default("")
},
async ({ featureName, initialDescription }) => {
// Create a new feature
const feature = createFeatureObject(featureName, initialDescription);
updateFeature(feature.id, feature);
// Get the first clarification question
const firstQuestion = getNextClarificationQuestion(feature);
return {
content: [{
type: "text",
text: `Feature ID: ${feature.id}\n\nLet's clarify your feature request. ${firstQuestion}`
}]
};
}
);
// Provide clarification tool
server.tool(
"provide_clarification",
{
featureId: z.string().min(1),
question: z.string().min(1),
answer: z.string().min(1)
},
async ({ featureId, question, answer }) => {
// Get the feature
const feature = getFeature(featureId);
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
// Add the clarification response to the feature
feature.clarificationResponses.push({
question,
answer,
timestamp: new Date()
});
// Save the feature with the updated clarification response
updateFeature(featureId, feature);
// Get the next question or indicate all questions are answered
const nextQuestion = getNextClarificationQuestion(feature);
if (nextQuestion) {
return {
content: [{
type: "text",
text: `Response recorded. ${nextQuestion}`
}]
};
} else {
// All questions answered
return {
content: [{
type: "text",
text: "All clarification questions have been answered. You can now generate a PRD for this feature."
}]
};
}
}
);
// Generate PRD tool
server.tool(
"generate_prd",
{
featureId: z.string().min(1)
},
async ({ featureId }) => {
const feature = getFeature(featureId);
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
if (!isClarificationComplete(feature)) {
throw new Error("Clarification process not complete. Please answer all clarification questions.");
}
const prd = generatePRD(feature);
feature.prd = prd;
updateFeature(featureId, feature);
return {
content: [{
type: "text",
text: `PRD generated successfully for "${feature.name}". You can view it at feature://${featureId}/prd`
}]
};
}
);
// Create phase tool
server.tool(
"create_phase",
{
featureId: z.string().min(1),
name: z.string().min(1),
description: z.string().min(1)
},
async ({ featureId, name, description }) => {
const feature = getFeature(featureId);
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
const phase = createPhaseDirectly(feature, name, description);
updateFeature(featureId, feature);
return {
content: [{
type: "text",
text: `Created phase "${name}" with ID ${phase.id} for feature "${feature.name}"`
}]
};
}
);
// Update phase status tool
server.tool(
"update_phase_status",
{
featureId: z.string().min(1),
phaseId: z.string().min(1),
status: z.enum(["pending", "in_progress", "completed", "reviewed"])
},
async ({ featureId, phaseId, status }) => {
const feature = getFeature(featureId);
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
throw new Error(`Phase ${phaseId} not found in feature ${featureId}`);
}
const oldStatus = phase.status;
updatePhaseStatusDirectly(feature, phaseId, status);
updateFeature(featureId, feature);
return {
content: [{
type: "text",
text: `Updated phase "${phase.name}" status from "${oldStatus}" to "${status}"`
}]
};
}
);
// Add task tool
server.tool(
"add_task",
{
featureId: z.string().min(1),
phaseId: z.string().min(1),
description: z.string().min(1)
},
async ({ featureId, phaseId, description }) => {
const feature = getFeature(featureId);
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
throw new Error(`Phase ${phaseId} not found in feature ${featureId}`);
}
const task = addTaskDirectly(feature, phaseId, description);
updateFeature(featureId, feature);
// Debug log
console.error(`DEBUG: Task created with ID: ${task.id}, type: ${typeof task.id}`);
console.error(`DEBUG: Task object: ${JSON.stringify(task)}`);
// Ensure task.id is explicitly converted to string and check if it's an object
let taskId: string;
if (typeof task.id === 'object') {
taskId = JSON.stringify(task.id);
} else {
taskId = String(task.id);
}
return {
content: [{
type: "text",
text: `Added task "${description.substring(0, 30)}${description.length > 30 ? '...' : ''}" with ID: ${taskId} to phase "${phase.name}"`
}]
};
}
);
// Update task status tool
server.tool(
"update_task_status",
{
featureId: z.string().min(1),
phaseId: z.string().min(1),
taskId: z.string().min(1),
completed: z.boolean()
},
async ({ featureId, phaseId, taskId, completed }) => {
const feature = getFeature(featureId);
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
throw new Error(`Phase ${phaseId} not found in feature ${featureId}`);
}
const task = phase.tasks.find(t => t.id === taskId);
if (!task) {
throw new Error(`Task ${taskId} not found in phase ${phaseId}`);
}
updateTaskStatusDirectly(feature, phaseId, taskId, completed);
updateFeature(featureId, feature);
return {
content: [{
type: "text",
text: `Updated task "${task.description.substring(0, 30)}${task.description.length > 30 ? '...' : ''}" status to ${completed ? 'completed' : 'not completed'}`
}]
};
}
);
// Get next phase action tool
server.tool(
"get_next_phase_action",
{
featureId: z.string().min(1)
},
async ({ featureId }) => {
const feature = getFeature(featureId);
if (!feature) {
throw new Error(`Feature ${featureId} not found`);
}
// Check if we need implementation plan first
if (!feature.implementationPlan) {
return {
content: [{
type: "text",
text: "You should generate an implementation plan before creating phases."
}]
};
}
// If no phases, suggest creating first phase
if (feature.phases.length === 0) {
return {
content: [{
type: "text",
text: "You should create the first development phase based on the implementation plan."
}]
};
}
// Find the current active phase (the first non-completed phase)
const currentPhase = feature.phases.find(p => p.status !== 'completed' && p.status !== 'reviewed');
if (!currentPhase) {
return {
content: [{
type: "text",
text: "All phases are complete. You should mark the final phase as reviewed."
}]
};
}
// Check if all tasks in the phase are completed
const allTasksCompleted = currentPhase.tasks.every(t => t.completed);
if (currentPhase.tasks.length === 0) {
return {
content: [{
type: "text",
text: `Current phase "${currentPhase.name}" has no tasks. You should add tasks based on the implementation plan.`
}]
};
} else if (!allTasksCompleted) {
const pendingTasks = currentPhase.tasks.filter(t => !t.completed);
return {
content: [{
type: "text",
text: `Current phase "${currentPhase.name}" has ${pendingTasks.length} incomplete tasks. Complete these tasks before moving to the next phase.`
}]
};
} else {
return {
content: [{
type: "text",
text: `All tasks in the current phase "${currentPhase.name}" are complete. You can now mark this phase as completed and proceed to the next phase.`
}]
};
}
}
);
// Define prompt for feature planning
server.prompt(
"feature-planning",
{
featureId: z.string()
},
({ featureId }) => ({
messages: [{
role: "user",
content: {
type: "text",
text: `I need to plan the development of feature with ID ${featureId}. Please help me:
1. Understand what the feature is about
2. Break down the feature into development phases
3. Create tasks for each phase
4. Track progress through completion`
}
}]
})
);
// Start the server
async function main() {
console.error("Starting Vibe-Coder MCP Server...");
const transport = new StdioServerTransport();
await server.connect(transport);
}
main().catch(error => {
console.error("Error in Vibe-Coder MCP Server:", error);
process.exit(1);
});
================
File: src/phases.ts
================
/**
* Phase management module for the Vibe-Coder MCP Server.
* This module handles the creation and management of development phases and tasks.
*/
import { Feature, Phase, Task, PhaseStatus } from './types.js';
import { updateFeature, getFeature } from './storage.js';
import { generateId, createPhaseObject, createTaskObject, isValidPhaseStatus, now } from './utils.js';
/**
* Define valid phase status transitions
* A map of current status to valid next statuses
*/
const VALID_PHASE_TRANSITIONS: Record<PhaseStatus, PhaseStatus[]> = {
'pending': ['in_progress'],
'in_progress': ['completed'],
'completed': ['reviewed'],
'reviewed': []
};
/**
* Create a new phase for a feature
* @param featureId The ID of the feature to create the phase for
* @param name The name of the phase
* @param description The description of the phase
* @returns The created phase or undefined if the feature is not found
*/
export function createPhase(
featureId: string,
name: string,
description: string
): Phase | undefined {
const feature = getFeature(featureId);
if (!feature) return undefined;
const newPhase = createPhaseObject(name, description);
updateFeature(featureId, {
phases: [...feature.phases, newPhase]
});
return newPhase;
}
/**
* Get a phase by ID
* @param featureId The ID of the feature
* @param phaseId The ID of the phase to get
* @returns The phase or undefined if not found
*/
export function getPhase(
featureId: string,
phaseId: string
): Phase | undefined {
const feature = getFeature(featureId);
if (!feature) return undefined;
return feature.phases.find(p => p.id === phaseId);
}
/**
* Add a new phase to a feature
* @param featureId The ID of the feature to add the phase to
* @param name The name of the phase
* @param description The description of the phase
* @returns The updated feature or undefined if not found
*/
export function addPhase(
featureId: string,
name: string,
description: string
): Feature | undefined {
const feature = getFeature(featureId);
if (!feature) return undefined;
const newPhase = createPhaseObject(name, description);
return updateFeature(featureId, {
phases: [...feature.phases, newPhase]
});
}
/**
* Add a task to a phase
* @param featureId The ID of the feature
* @param phaseId The ID of the phase to add the task to
* @param description The description of the task
* @returns The updated feature or undefined if not found
*/
export function addTask(
featureId: string,
phaseId: string,
description: string
): Feature | undefined {
const feature = getFeature(featureId);
if (!feature) return undefined;
const phaseIndex = feature.phases.findIndex(p => p.id === phaseId);
if (phaseIndex === -1) return undefined;
const newTask = createTaskObject(description);
const updatedPhases = [...feature.phases];
updatedPhases[phaseIndex] = {
...updatedPhases[phaseIndex],
tasks: [...updatedPhases[phaseIndex].tasks, newTask],
updatedAt: now()
};
return updateFeature(featureId, { phases: updatedPhases });
}
/**
* Update the status of a phase
* @param featureId The ID of the feature
* @param phaseId The ID of the phase to update
* @param status The new status
* @returns The updated feature or undefined if not found
*/
export function updatePhaseStatus(
featureId: string,
phaseId: string,
status: PhaseStatus
): Feature | undefined {
const feature = getFeature(featureId);
if (!feature) return undefined;
const phaseIndex = feature.phases.findIndex(p => p.id === phaseId);
if (phaseIndex === -1) return undefined;
// Validate the status transition
const phase = feature.phases[phaseIndex];
const validationResult = validatePhaseTransition(phase.status, status);
if (!validationResult.valid) {
console.error(validationResult.message);
return undefined;
}
const updatedPhases = [...feature.phases];
updatedPhases[phaseIndex] = {
...updatedPhases[phaseIndex],
status,
updatedAt: now()
};
return updateFeature(featureId, { phases: updatedPhases });
}
/**
* Update a task's completion status
* @param featureId The ID of the feature
* @param phaseId The ID of the phase
* @param taskId The ID of the task to update
* @param completed Whether the task is completed
* @returns The updated feature or undefined if not found
*/
export function updateTaskStatus(
featureId: string,
phaseId: string,
taskId: string,
completed: boolean
): Feature | undefined {
const feature = getFeature(featureId);
if (!feature) return undefined;
const phaseIndex = feature.phases.findIndex(p => p.id === phaseId);
if (phaseIndex === -1) return undefined;
const taskIndex = feature.phases[phaseIndex].tasks.findIndex(t => t.id === taskId);
if (taskIndex === -1) return undefined;
const updatedPhases = [...feature.phases];
const updatedTasks = [...updatedPhases[phaseIndex].tasks];
updatedTasks[taskIndex] = {
...updatedTasks[taskIndex],
completed,
updatedAt: now()
};
updatedPhases[phaseIndex] = {
...updatedPhases[phaseIndex],
tasks: updatedTasks,
updatedAt: now()
};
return updateFeature(featureId, { phases: updatedPhases });
}
/**
* Validate a phase status transition
* @param currentStatus The current status
* @param newStatus The proposed new status
* @returns An object with valid flag and message
*/
export function validatePhaseTransition(
currentStatus: PhaseStatus,
newStatus: PhaseStatus
): { valid: boolean; message: string } {
// Allow same status
if (currentStatus === newStatus) {
return { valid: true, message: "Status unchanged" };
}
// Check if the status is valid
if (!isValidPhaseStatus(newStatus)) {
return {
valid: false,
message: `Invalid status: ${newStatus}. Valid statuses are: pending, in_progress, completed, reviewed`
};
}
// Check if the transition is valid
const validNextStatuses = VALID_PHASE_TRANSITIONS[currentStatus];
if (!validNextStatuses.includes(newStatus)) {
return {
valid: false,
message: `Invalid transition from ${currentStatus} to ${newStatus}. Valid next statuses are: ${validNextStatuses.join(', ')}`
};
}
return { valid: true, message: "Valid transition" };
}
/**
* Get the next logical status for a phase
* @param currentStatus The current status
* @returns The recommended next status, or null if no valid transition
*/
export function getNextPhaseStatus(currentStatus: PhaseStatus): PhaseStatus | null {
const validNextStatuses = VALID_PHASE_TRANSITIONS[currentStatus];
if (validNextStatuses.length === 0) {
return null;
}
return validNextStatuses[0];
}
/**
* Get a summary of the phases for a feature
* @param featureId The ID of the feature
* @returns A text summary of the phases
*/
export function getPhaseSummary(featureId: string): string {
const feature = getFeature(featureId);
if (!feature) return "Feature not found";
if (feature.phases.length === 0) {
return "No phases defined for this feature yet.";
}
const phasesSummary = feature.phases.map(phase => {
const completedTasks = phase.tasks.filter(t => t.completed).length;
const totalTasks = phase.tasks.length;
return `${phase.name} (${phase.status}): ${completedTasks}/${totalTasks} tasks completed`;
}).join('\n');
return `Phases for ${feature.name}:\n${phasesSummary}`;
}
/**
* Initialize default phases for a feature based on its implementation plan
* @param featureId The ID of the feature
* @returns The updated feature or undefined if not found
*/
export function initializeDefaultPhases(featureId: string): Feature | undefined {
const feature = getFeature(featureId);
if (!feature) return undefined;
// If the feature already has phases, don't override them
if (feature.phases && feature.phases.length > 0) {
return feature;
}
// Create default phases
const defaultPhases = [
createPhaseObject(
"Requirements Analysis and Design",
"Analyze requirements, design the architecture, and create a detailed implementation plan."
),
createPhaseObject(
"Core Implementation",
"Implement the core functionality based on the design."
),
createPhaseObject(
"Testing and Integration",
"Test all components, integrate with existing systems, and refine the implementation."
),
createPhaseObject(
"Documentation and Finalization",
"Finalize documentation, clean up code, and prepare for deployment."
)
];
// Add default tasks for each phase
const phase1 = defaultPhases[0];
addTask(featureId, phase1.id, "Review and analyze clarification responses");
addTask(featureId, phase1.id, "Identify key components and their interactions");
addTask(featureId, phase1.id, "Design the system architecture");
addTask(featureId, phase1.id, "Create UML diagrams if necessary");
addTask(featureId, phase1.id, "Identify potential edge cases and risks");
const phase2 = defaultPhases[1];
addTask(featureId, phase2.id, "Set up project structure and dependencies");
addTask(featureId, phase2.id, "Implement data models and interfaces");
addTask(featureId, phase2.id, "Build core business logic");
addTask(featureId, phase2.id, "Create unit tests for core functionality");
addTask(featureId, phase2.id, "Ensure code follows best practices");
const phase3 = defaultPhases[2];
addTask(featureId, phase3.id, "Write unit tests for all components");
addTask(featureId, phase3.id, "Perform integration testing");
addTask(featureId, phase3.id, "Fix bugs and edge cases");
addTask(featureId, phase3.id, "Optimize performance");
addTask(featureId, phase3.id, "Document any known limitations");
const phase4 = defaultPhases[3];
addTask(featureId, phase4.id, "Complete inline code documentation");
addTask(featureId, phase4.id, "Create user documentation");
addTask(featureId, phase4.id, "Clean up and refactor code");
addTask(featureId, phase4.id, "Prepare deployment strategy");
addTask(featureId, phase4.id, "Create final pull request");
return updateFeature(featureId, { phases: defaultPhases });
}
================
File: src/registry.ts
================
/**
* @file registry.ts
* @version 1.1.0
*
* Provides registries for tools and resources in the Vibe-Coder MCP Server.
* These registries manage URI templates, matching, and tool handlers.
*/
import { ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
import { ErrorCode, createErrorResponse, createToolErrorResponse } from './errors.js';
import { Feature } from './types.js';
// --------- Tool Registry ---------
/**
* Type for tool handler function
*/
export type ToolHandler<T = any> = (params: T) => Promise<any>;
/**
* Tool metadata type
*/
export interface ToolMetadata {
description: string;
inputSchema: any;
examples?: any[];
}
/**
* Tool registry to map tool names to their handler functions and metadata
*/
export class ToolRegistry {
private handlers: Map<string, ToolHandler> = new Map();
private toolMetadata: Map<string, ToolMetadata> = new Map();
/**
* Register a tool handler with metadata
* @param name Tool name
* @param handler Tool handler function
* @param description Tool description
* @param inputSchema Tool input schema
* @param examples Optional examples for the tool
*/
register<T>(
name: string,
handler: ToolHandler<T>,
description: string,
inputSchema: any,
examples?: any[]
): void {
this.handlers.set(name, handler);
this.toolMetadata.set(name, {
description,
inputSchema,
examples
});
}
/**
* Get a tool handler by name
* @param name Tool name
* @returns The tool handler function or undefined if not found
*/
getHandler(name: string): ToolHandler | undefined {
return this.handlers.get(name);
}
/**
* Get tool metadata by name
* @param name Tool name
* @returns The tool metadata or undefined if not found
*/
getMetadata(name: string): ToolMetadata | undefined {
return this.toolMetadata.get(name);
}
/**
* Check if a tool exists
* @param name Tool name
* @returns True if the tool exists
*/
hasHandler(name: string): boolean {
return this.handlers.has(name);
}
/**
* Execute a tool by name with parameters
* @param name Tool name
* @param params Tool parameters
* @returns The tool execution result
*/
async execute(name: string, params: any): Promise<any> {
const handler = this.getHandler(name);
if (!handler) {
return createToolErrorResponse(`Unknown tool "${name}"`);
}
try {
return await handler(params);
} catch (error) {
console.error(`Error executing tool ${name}:`, error);
return createToolErrorResponse(
error instanceof Error ? error.message : "Internal server error"
);
}
}
/**
* List all registered tools with their metadata
* @returns Array of tool information objects
*/
listTools(): { name: string; description: string; inputSchema: any; examples?: any[] }[] {
return Array.from(this.handlers.keys()).map((name) => {
const metadata = this.toolMetadata.get(name);
return {
name,
description: metadata?.description || "No description provided",
inputSchema: metadata?.inputSchema || {},
examples: metadata?.examples
};
});
}
}
// --------- Resource Registry ---------
/**
* Resource handler type
*/
export type ResourceHandler = (uri: URL, params: Record<string, string>) => Promise<any>;
/**
* Resource registry entry
*/
type ResourceRegistryEntry = {
template: ResourceTemplate;
handler: ResourceHandler;
};
/**
* Resource registry for managing URI templates and handlers
*/
export class ResourceRegistry {
private resources: ResourceRegistryEntry[] = [];
/**
* Register a resource with a template and handler
*/
register(template: ResourceTemplate, handler: ResourceHandler): void {
this.resources.push({ template, handler });
}
/**
* Find a matching resource and extract parameters
*/
findMatch(uri: string): { handler: ResourceHandler; params: Record<string, string> } | undefined {
const url = new URL(uri);
for (const { template, handler } of this.resources) {
const match = this.matchTemplate(url, template);
if (match) {
return { handler, params: match };
}
}
return undefined;
}
/**
* Match a URL against a template and extract parameters
*/
private matchTemplate(url: URL, template: ResourceTemplate): Record<string, string> | undefined {
// Convert template to regex pattern
const pattern = this.templateToPattern(template.pattern);
const regex = new RegExp(pattern.pattern);
// Match against the full URL
const match = regex.exec(url.href);
if (!match) {
return undefined;
}
// Extract named parameters
const params: Record<string, string> = {};
pattern.paramNames.forEach((name, index) => {
params[name] = match[index + 1] || '';
});
return params;
}
/**
* Convert a URI template to a regex pattern
* Handles {param} syntax in templates
*/
private templateToPattern(template: string): { pattern: string; paramNames: string[] } {
const paramNames: string[] = [];
let pattern = template.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
// Replace {param} with capture groups
pattern = pattern.replace(/\{([a-zA-Z0-9_]+)\}/g, (_, name) => {
paramNames.push(name);
return '([^/]+)';
});
// Replace * with wildcard
pattern = pattern.replace(/\\\*/g, '.*');
// Anchor to start of string
pattern = `^${pattern}$`;
return { pattern, paramNames };
}
/**
* List all registered resources
* @returns Array of resource templates
*/
listResources(): { template: string }[] {
return this.resources.map(({ template }) => ({
template: template.pattern
}));
}
}
// Create global instances
export const toolRegistry = new ToolRegistry();
export const resourceRegistry = new ResourceRegistry();
================
File: src/resource-handlers.ts
================
/**
* @file resource-handlers.ts
* @version 1.0.0
*
* Provides handlers for resources exposed by the Vibe-Coder MCP Server.
* These handlers are registered with the resource registry for consistent handling.
*/
import { ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
import { resourceRegistry, ResourceHandler } from './registry.js';
import { Feature } from './types.js';
import { listFeatures, getFeature } from './storage.js';
import { formatClarificationResponses } from './clarification.js';
import { generatePRD, generateImplementationPlan } from './documentation.js';
import { generateFeatureProgressSummary } from './utils.js';
import { ErrorCode, createErrorResponse } from './errors.js';
/**
* Define resource templates for all resources
*/
const RESOURCE_TEMPLATES = {
featuresList: new ResourceTemplate('features://list', { list: undefined }),
featuresStatus: new ResourceTemplate('features://status', { list: undefined }),
featureDetail: new ResourceTemplate('feature://{featureId}', { list: undefined }),
featureProgress: new ResourceTemplate('feature://{featureId}/progress', { list: undefined }),
featurePrd: new ResourceTemplate('feature://{featureId}/prd', { list: undefined }),
featureImplementation: new ResourceTemplate('feature://{featureId}/implementation', { list: undefined }),
featurePhases: new ResourceTemplate('feature://{featureId}/phases', { list: undefined }),
featureTasks: new ResourceTemplate('feature://{featureId}/tasks', { list: undefined }),
phaseDetail: new ResourceTemplate('feature://{featureId}/phase/{phaseId}', { list: undefined }),
phaseTasks: new ResourceTemplate('feature://{featureId}/phase/{phaseId}/tasks', { list: undefined }),
taskDetail: new ResourceTemplate('feature://{featureId}/phase/{phaseId}/task/{taskId}', { list: undefined }),
};
/**
* Handler for the features list resource
*/
const featuresListHandler: ResourceHandler = async (uri, params) => {
return {
contents: [{
uri: uri.href,
mimeType: "text/plain",
text: listFeatures().map(f => `${f.id}: ${f.name}`).join("\n")
}]
};
};
/**
* Handler for the features status resource
*/
const featuresStatusHandler: ResourceHandler = async (uri, params) => {
const features = listFeatures();
if (features.length === 0) {
return {
contents: [{
uri: uri.href,
mimeType: "text/markdown",
text: "# Project Status\n\nNo features have been created yet."
}]
};
}
const featuresStatus = features.map(feature => {
const totalPhases = feature.phases.length;
const completedPhases = feature.phases.filter(p => p.status === 'completed' || p.status === 'reviewed').length;
const totalTasks = feature.phases.reduce((acc, phase) => acc + phase.tasks.length, 0);
const completedTasks = feature.phases.reduce(
(acc, phase) => acc + phase.tasks.filter(t => t.completed).length, 0
);
return `## ${feature.name}
- ID: ${feature.id}
- Status: ${completedPhases === totalPhases && totalPhases > 0 ? 'Completed' : 'In Progress'}
- Phases: ${completedPhases}/${totalPhases} completed
- Tasks: ${completedTasks}/${totalTasks} completed
- [View Details](feature://${feature.id}/progress)
`;
}).join('\n');
return {
contents: [{
uri: uri.href,
mimeType: "text/markdown",
text: `# Project Status\n\n${featuresStatus}`
}]
};
};
/**
* Handler for the feature detail resource
*/
const featureDetailHandler: ResourceHandler = async (uri, params) => {
const featureId = params.featureId;
const feature = getFeature(featureId);
if (!feature) {
return createErrorResponse(ErrorCode.FEATURE_NOT_FOUND, `Feature ${featureId} not found`);
}
const timestamp = feature.updatedAt.toISOString();
const clarifications = formatClarificationResponses(feature.clarificationResponses);
const phasesText = feature.phases.map(p =>
`- ${p.name} (${p.status}): ${p.tasks.filter(t => t.completed).length}/${p.tasks.length} tasks completed`
).join('\n');
const featureDetails = `
Feature: ${feature.name}
ID: ${feature.id}
Description: ${feature.description}
Last Updated: ${timestamp}
Clarification Responses:
${clarifications}
Phases (${feature.phases.length}):
${phasesText}
`;
return {
contents: [{
uri: uri.href,
mimeType: "text/plain",
text: featureDetails
}]
};
};
/**
* Handler for the feature progress resource
*/
const featureProgressHandler: ResourceHandler = async (uri, params) => {
const featureId = params.featureId;
const feature = getFeature(featureId);
if (!feature) {
return createErrorResponse(ErrorCode.FEATURE_NOT_FOUND, `Feature ${featureId} not found`);
}
const progressReport = generateFeatureProgressSummary(feature);
return {
contents: [{
uri: uri.href,
mimeType: "text/markdown",
text: progressReport
}]
};
};
/**
* Handler for the feature PRD resource
*/
const featurePrdHandler: ResourceHandler = async (uri, params) => {
const featureId = params.featureId;
const feature = getFeature(featureId);
if (!feature) {
return createErrorResponse(ErrorCode.FEATURE_NOT_FOUND, `Feature ${featureId} not found`);
}
const prdContent = feature.prdDoc || generatePRD(feature);
return {
contents: [{
uri: uri.href,
mimeType: "text/markdown",
text: prdContent
}]
};
};
/**
* Handler for the feature implementation plan resource
*/
const featureImplementationHandler: ResourceHandler = async (uri, params) => {
const featureId = params.featureId;
const feature = getFeature(featureId);
if (!feature) {
return createErrorResponse(ErrorCode.FEATURE_NOT_FOUND, `Feature ${featureId} not found`);
}
const implContent = feature.implDoc || generateImplementationPlan(feature);
return {
contents: [{
uri: uri.href,
mimeType: "text/markdown",
text: implContent
}]
};
};
/**
* Handler for the feature phases resource
*/
const featurePhasesHandler: ResourceHandler = async (uri, params) => {
const featureId = params.featureId;
const feature = getFeature(featureId);
if (!feature) {
return createErrorResponse(ErrorCode.FEATURE_NOT_FOUND, `Feature ${featureId} not found`);
}
if (feature.phases.length === 0) {
return {
contents: [{
uri: uri.href,
mimeType: "text/plain",
text: `No phases defined for feature: ${feature.name}`
}]
};
}
const phasesContent = feature.phases.map(phase => {
const completedTasks = phase.tasks.filter(t => t.completed).length;
const totalTasks = phase.tasks.length;
return `Phase: ${phase.name} (ID: ${phase.id})
Status: ${phase.status}
Description: ${phase.description}
Progress: ${completedTasks}/${totalTasks} tasks completed
Last Updated: ${phase.updatedAt.toISOString()}
`;
}).join('\n---\n\n');
return {
contents: [{
uri: uri.href,
mimeType: "text/plain",
text: `# Phases for Feature: ${feature.name}\n\n${phasesContent}`
}]
};
};
/**
* Handler for the feature tasks resource
*/
const featureTasksHandler: ResourceHandler = async (uri, params) => {
const featureId = params.featureId;
const feature = getFeature(featureId);
if (!feature) {
return createErrorResponse(ErrorCode.FEATURE_NOT_FOUND, `Feature ${featureId} not found`);
}
const allTasks = feature.phases.flatMap(phase =>
phase.tasks.map(task => ({
...task,
phaseName: phase.name,
phaseId: phase.id,
phaseStatus: phase.status
}))
);
if (allTasks.length === 0) {
return {
contents: [{
uri: uri.href,
mimeType: "text/plain",
text: `No tasks defined for feature: ${feature.name}`
}]
};
}
const pendingTasks = allTasks.filter(t => !t.completed);
const completedTasks = allTasks.filter(t => t.completed);
const pendingTasksText = pendingTasks.length > 0
? pendingTasks.map(task => `- [ ] ${task.description} (ID: ${task.id}, Phase: ${task.phaseName})`).join('\n')
: "No pending tasks.";
const completedTasksText = completedTasks.length > 0
? completedTasks.map(task => `- [x] ${task.description} (ID: ${task.id}, Phase: ${task.phaseName})`).join('\n')
: "No completed tasks.";
const tasksContent = `# All Tasks for Feature: ${feature.name}
## Pending Tasks (${pendingTasks.length})
${pendingTasksText}
## Completed Tasks (${completedTasks.length})
${completedTasksText}
`;
return {
contents: [{
uri: uri.href,
mimeType: "text/plain",
text: tasksContent
}]
};
};
/**
* Handler for the phase detail resource
*/
const phaseDetailHandler: ResourceHandler = async (uri, params) => {
const featureId = params.featureId;
const phaseId = params.phaseId;
const feature = getFeature(featureId);
if (!feature) {
return createErrorResponse(ErrorCode.FEATURE_NOT_FOUND, `Feature ${featureId} not found`);
}
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
return createErrorResponse(ErrorCode.PHASE_NOT_FOUND, `Phase ${phaseId} not found in feature ${feature.name}`);
}
const completedTasks = phase.tasks.filter(t => t.completed).length;
const totalTasks = phase.tasks.length;
const taskList = phase.tasks.map(task =>
`- [${task.completed ? 'x' : ' '}] ${task.description} (ID: ${task.id})`
).join('\n');
const phaseDetails = `
Phase: ${phase.name}
ID: ${phase.id}
Status: ${phase.status}
Description: ${phase.description}
Created: ${phase.createdAt.toISOString()}
Last Updated: ${phase.updatedAt.toISOString()}
Progress: ${completedTasks}/${totalTasks} tasks completed
Tasks:
${taskList}
`;
return {
contents: [{
uri: uri.href,
mimeType: "text/plain",
text: phaseDetails
}]
};
};
/**
* Handler for the phase tasks resource
*/
const phaseTasksHandler: ResourceHandler = async (uri, params) => {
const featureId = params.featureId;
const phaseId = params.phaseId;
const feature = getFeature(featureId);
if (!feature) {
return createErrorResponse(ErrorCode.FEATURE_NOT_FOUND, `Feature ${featureId} not found`);
}
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
return createErrorResponse(ErrorCode.PHASE_NOT_FOUND, `Phase ${phaseId} not found in feature ${feature.name}`);
}
if (phase.tasks.length === 0) {
return {
contents: [{
uri: uri.href,
mimeType: "text/plain",
text: `No tasks defined for phase: ${phase.name}`
}]
};
}
const tasksContent = phase.tasks.map(task => `
Task: ${task.description}
ID: ${task.id}
Status: ${task.completed ? 'Completed' : 'Pending'}
Created: ${task.createdAt.toISOString()}
Last Updated: ${task.updatedAt.toISOString()}
`).join('\n---\n');
return {
contents: [{
uri: uri.href,
mimeType: "text/plain",
text: `# Tasks for Phase: ${phase.name}\n\n${tasksContent}`
}]
};
};
/**
* Handler for the task detail resource
*/
const taskDetailHandler: ResourceHandler = async (uri, params) => {
const featureId = params.featureId;
const phaseId = params.phaseId;
const taskId = params.taskId;
const feature = getFeature(featureId);
if (!feature) {
return createErrorResponse(ErrorCode.FEATURE_NOT_FOUND, `Feature ${featureId} not found`);
}
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
return createErrorResponse(ErrorCode.PHASE_NOT_FOUND, `Phase ${phaseId} not found in feature ${feature.name}`);
}
const task = phase.tasks.find(t => t.id === taskId);
if (!task) {
return createErrorResponse(ErrorCode.TASK_NOT_FOUND, `Task ${taskId} not found in phase ${phase.name}`);
}
const taskDetails = `
Task: ${task.description}
ID: ${task.id}
Status: ${task.completed ? 'Completed' : 'Pending'}
Created: ${task.createdAt.toISOString()}
Last Updated: ${task.updatedAt.toISOString()}
`;
return {
contents: [{
uri: uri.href,
mimeType: "text/plain",
text: taskDetails
}]
};
};
/**
* Register all resource handlers
*/
export function registerResourceHandlers() {
resourceRegistry.register(RESOURCE_TEMPLATES.featuresList, featuresListHandler);
resourceRegistry.register(RESOURCE_TEMPLATES.featuresStatus, featuresStatusHandler);
resourceRegistry.register(RESOURCE_TEMPLATES.featureDetail, featureDetailHandler);
resourceRegistry.register(RESOURCE_TEMPLATES.featureProgress, featureProgressHandler);
resourceRegistry.register(RESOURCE_TEMPLATES.featurePrd, featurePrdHandler);
resourceRegistry.register(RESOURCE_TEMPLATES.featureImplementation, featureImplementationHandler);
resourceRegistry.register(RESOURCE_TEMPLATES.featurePhases, featurePhasesHandler);
resourceRegistry.register(RESOURCE_TEMPLATES.featureTasks, featureTasksHandler);
resourceRegistry.register(RESOURCE_TEMPLATES.phaseDetail, phaseDetailHandler);
resourceRegistry.register(RESOURCE_TEMPLATES.phaseTasks, phaseTasksHandler);
resourceRegistry.register(RESOURCE_TEMPLATES.taskDetail, taskDetailHandler);
}
// Export individual handlers for testing or direct usage
export {
featuresListHandler,
featuresStatusHandler,
featureDetailHandler,
featureProgressHandler,
featurePrdHandler,
featureImplementationHandler,
featurePhasesHandler,
featureTasksHandler,
phaseDetailHandler,
phaseTasksHandler,
taskDetailHandler
};
================
File: src/schemas.ts
================
/**
* @file schemas.ts
* @version 1.0.0
*
* Provides Zod schemas and branded types for the Vibe-Coder MCP Server.
* These schemas enable runtime validation and improve type safety across the codebase.
*/
import { z } from 'zod';
import { PhaseStatus } from './types.js';
// --------- Branded Types for IDs ---------
/**
* Branded type for Feature IDs
*/
export type FeatureId = string & { readonly _brand: unique symbol };
/**
* Branded type for Phase IDs
*/
export type PhaseId = string & { readonly _brand: unique symbol };
/**
* Branded type for Task IDs
*/
export type TaskId = string & { readonly _brand: unique symbol };
/**
* Type guards for branded types
*/
export const isFeatureId = (id: string): id is FeatureId => id.startsWith('feature-');
export const isPhaseId = (id: string): id is PhaseId => id.startsWith('phase-');
export const isTaskId = (id: string): id is TaskId => id.startsWith('task-');
/**
* Brand creator functions
*/
export const createFeatureId = (id: string): FeatureId => {
if (!isFeatureId(id)) throw new Error(`Invalid feature ID format: ${id}`);
return id as FeatureId;
};
export const createPhaseId = (id: string): PhaseId => {
if (!isPhaseId(id)) throw new Error(`Invalid phase ID format: ${id}`);
return id as PhaseId;
};
export const createTaskId = (id: string): TaskId => {
if (!isTaskId(id)) throw new Error(`Invalid task ID format: ${id}`);
return id as TaskId;
};
// --------- Core Zod Schemas ---------
/**
* Schema for ClarificationResponse
*/
export const ClarificationResponseSchema = z.object({
question: z.string().min(1, "Question cannot be empty"),
answer: z.string().min(1, "Answer cannot be empty"),
timestamp: z.date(),
});
/**
* Schema for Task
*/
export const TaskSchema = z.object({
id: z.string().refine(isTaskId, "Invalid task ID format"),
description: z.string().min(3, "Task description must be at least 3 characters"),
completed: z.boolean(),
createdAt: z.date(),
updatedAt: z.date(),
});
/**
* Schema for PhaseStatus
*/
export const PhaseStatusSchema = z.enum(["pending", "in_progress", "completed", "reviewed"]);
/**
* Schema for Phase
*/
export const PhaseSchema = z.object({
id: z.string().refine(isPhaseId, "Invalid phase ID format"),
name: z.string().min(2, "Phase name must be at least 2 characters").max(100, "Phase name must be at most 100 characters"),
description: z.string(),
tasks: z.array(TaskSchema),
status: PhaseStatusSchema,
createdAt: z.date(),
updatedAt: z.date(),
});
/**
* Schema for Feature
*/
export const FeatureSchema = z.object({
id: z.string().refine(isFeatureId, "Invalid feature ID format"),
name: z.string().min(2, "Feature name must be at least 2 characters").max(100, "Feature name must be at most 100 characters"),
description: z.string(),
clarificationResponses: z.array(ClarificationResponseSchema),
prd: z.string().optional(),
prdDoc: z.string().optional(),
implementationPlan: z.string().optional(),
implDoc: z.string().optional(),
phases: z.array(PhaseSchema),
createdAt: z.date(),
updatedAt: z.date(),
});
// --------- Type Inference ---------
/**
* Zod-inferred types to ensure schema and type compatibility
*/
export type ZodFeature = z.infer<typeof FeatureSchema>;
export type ZodPhase = z.infer<typeof PhaseSchema>;
export type ZodTask = z.infer<typeof TaskSchema>;
export type ZodClarificationResponse = z.infer<typeof ClarificationResponseSchema>;
/**
* Validation functions for inputs
*/
export const validateFeature = (feature: unknown): ZodFeature => {
return FeatureSchema.parse(feature);
};
export const validatePhase = (phase: unknown): ZodPhase => {
return PhaseSchema.parse(phase);
};
export const validateTask = (task: unknown): ZodTask => {
return TaskSchema.parse(task);
};
export const validateClarificationResponse = (response: unknown): ZodClarificationResponse => {
return ClarificationResponseSchema.parse(response);
};
================
File: src/storage.ts
================
/**
* In-memory storage for features and related data.
*/
import { Feature, FeatureStorage } from './types.js';
/**
* In-memory storage for features
*/
export const features: FeatureStorage = {};
/**
* Add a new feature to storage
* @param feature The feature to store
* @returns The stored feature
*/
export function storeFeature(feature: Feature): Feature {
features[feature.id] = feature;
return feature;
}
/**
* Retrieve a feature by ID
* @param id The feature ID
* @returns The feature or undefined if not found
*/
export function getFeature(id: string): Feature | undefined {
return features[id];
}
/**
* Update an existing feature
* @param id The feature ID
* @param updatedFields Fields to update on the feature
* @returns The updated feature or undefined if not found
*/
export function updateFeature(
id: string,
updatedFields: Partial<Omit<Feature, 'id' | 'createdAt'>>
): Feature | undefined {
const feature = features[id];
if (!feature) {
return undefined;
}
// Update the feature with new fields
const updatedFeature = {
...feature,
...updatedFields,
updatedAt: new Date()
};
features[id] = updatedFeature;
return updatedFeature;
}
/**
* List all features
* @returns Array of all features
*/
export function listFeatures(): Feature[] {
return Object.values(features);
}
/**
* Delete a feature by ID
* @param id The feature ID
* @returns True if deleted, false if not found
*/
export function deleteFeature(id: string): boolean {
if (features[id]) {
delete features[id];
return true;
}
return false;
}
================
File: src/test-mcp-improved.js
================
#!/usr/bin/env node
/**
* @file test-mcp-improved.js
*
* Test script for the improved MCP server implementation.
* Tests the tool registry, resource registry, and error handling.
*/
const { spawn } = require('child_process');
const path = require('path');
// Path to the MCP server
const SERVER_PATH = path.join(__dirname, 'index-updated.ts');
// Store responses and state
const responses = [];
let featureId = null;
// Start the MCP server process
const server = spawn('ts-node', [SERVER_PATH], {
stdio: ['pipe', 'pipe', process.stderr]
});
// Handle server's stdout
server.stdout.on('data', (data) => {
try {
const lines = data.toString().trim().split('\n');
for (const line of lines) {
if (!line.trim()) continue;
// Parse the JSON response
const response = JSON.parse(line);
responses.push(response);
// Process the response based on its type
processResponse(response);
}
} catch (error) {
console.error('Error processing server response:', error);
}
});
// Process a server response
function processResponse(response) {
if (response.id === 'init') {
sendInitialized();
} else if (response.id === 'start-feature') {
// Extract feature ID from the response
const content = response.result?.content[0]?.text;
if (content) {
const match = content.match(/Feature ID: ([a-z0-9-]+)/);
if (match) {
featureId = match[1];
console.log(`\nCreated feature with ID: ${featureId}`);
// Ask the first clarification question
sendProvideClarification(featureId, 'What problem does this feature solve?', 'The feature solves the problem of managing test data across different environments.');
}
}
} else if (response.id === 'clarify-1') {
sendProvideClarification(featureId, 'Who are the target users?', 'Developers and QA engineers who need to create, manage, and share test data.');
} else if (response.id === 'clarify-2') {
sendProvideClarification(featureId, 'What are the key requirements?', 'Data import/export, version control integration, and user-friendly interface.');
} else if (response.id === 'clarify-3') {
sendProvideClarification(featureId, 'What are the success criteria?', 'Users can create and manage test data across environments with minimal effort.');
} else if (response.id === 'clarify-4') {
sendProvideClarification(featureId, 'Any technical constraints?', 'Must work with existing database systems and be containerizable.');
} else if (response.id === 'clarify-5') {
console.log('\nAll clarification questions answered.');
// Generate PRD
sendGeneratePRD(featureId);
} else if (response.id === 'generate-prd') {
// Generate implementation plan
sendGenerateImplementationPlan(featureId);
} else if (response.id === 'generate-implementation-plan') {
// Create a phase
sendCreatePhase(featureId);
} else if (response.id === 'create-phase') {
// Extract phase ID from the response
const content = response.result?.content[0]?.text;
if (content) {
const match = content.match(/ID: ([a-z0-9-]+)/);
if (match) {
const phaseId = match[1];
console.log(`\nCreated phase with ID: ${phaseId}`);
// Update phase status
sendUpdatePhaseStatus(featureId, phaseId, 'in_progress');
}
}
} else if (response.id === 'update-phase-status') {
// Get feature details
sendReadResource(`feature://${featureId}`);
} else if (response.id === 'read-feature') {
// Test resource handler
sendReadResource(`feature://${featureId}/progress`);
} else if (response.id === 'read-progress') {
// Test list resources
sendListResources();
} else if (response.id === 'list-resources') {
// Test list tools
sendListTools();
} else if (response.id === 'list-tools') {
// All tests completed
console.log('\nAll tests completed successfully.');
// Clean up
server.stdin.end();
process.exit(0);
}
}
// Send initialization message
function sendInitialize() {
const message = {
jsonrpc: '2.0',
id: 'init',
method: 'initialize',
params: {
processId: process.pid,
clientInfo: {
name: 'MCP Test Client',
version: '1.0.0'
},
capabilities: {
resources: {},
tools: {},
prompts: {}
}
}
};
sendMessage(message);
}
// Send initialized notification
function sendInitialized() {
const message = {
jsonrpc: '2.0',
method: 'initialized',
params: {}
};
sendMessage(message);
// Start the tests after initialization
console.log('\nStarting tests...');
sendStartFeature();
}
// Send a message to start feature clarification
function sendStartFeature() {
const message = {
jsonrpc: '2.0',
id: 'start-feature',
method: 'callTool',
params: {
name: 'start_feature_clarification',
arguments: {
featureName: 'Test Data Manager',
initialDescription: 'A tool for managing test data across various environments.'
}
}
};
sendMessage(message);
}
// Send a message to provide clarification
function sendProvideClarification(featureId, question, answer) {
// Use a different ID for each clarification to track them
const clarificationId = `clarify-${responses.filter(r => r.id && r.id.startsWith('clarify-')).length + 1}`;
const message = {
jsonrpc: '2.0',
id: clarificationId,
method: 'callTool',
params: {
name: 'provide_clarification',
arguments: {
featureId,
question,
answer
}
}
};
sendMessage(message);
}
// Send a message to generate a PRD
function sendGeneratePRD(featureId) {
const message = {
jsonrpc: '2.0',
id: 'generate-prd',
method: 'callTool',
params: {
name: 'generate_prd',
arguments: {
featureId
}
}
};
sendMessage(message);
}
// Send a message to generate an implementation plan
function sendGenerateImplementationPlan(featureId) {
const message = {
jsonrpc: '2.0',
id: 'generate-implementation-plan',
method: 'callTool',
params: {
name: 'generate_implementation_plan',
arguments: {
featureId
}
}
};
sendMessage(message);
}
// Send a message to create a phase
function sendCreatePhase(featureId) {
const message = {
jsonrpc: '2.0',
id: 'create-phase',
method: 'callTool',
params: {
name: 'create_phase',
arguments: {
featureId,
name: 'Design',
description: 'Design the architecture and user interface for the Test Data Manager.'
}
}
};
sendMessage(message);
}
// Send a message to update phase status
function sendUpdatePhaseStatus(featureId, phaseId, status) {
const message = {
jsonrpc: '2.0',
id: 'update-phase-status',
method: 'callTool',
params: {
name: 'update_phase_status',
arguments: {
featureId,
phaseId,
status
}
}
};
sendMessage(message);
}
// Send a message to read a resource
function sendReadResource(uri) {
const message = {
jsonrpc: '2.0',
id: uri.includes('progress') ? 'read-progress' : 'read-feature',
method: 'readResource',
params: {
uri
}
};
sendMessage(message);
}
// Send a message to list resources
function sendListResources() {
const message = {
jsonrpc: '2.0',
id: 'list-resources',
method: 'listResources',
params: {}
};
sendMessage(message);
}
// Send a message to list tools
function sendListTools() {
const message = {
jsonrpc: '2.0',
id: 'list-tools',
method: 'listTools',
params: {}
};
sendMessage(message);
}
// Send a message to the server
function sendMessage(message) {
const json = JSON.stringify(message);
server.stdin.write(json + '\n');
}
// Start the test
sendInitialize();
// Handle process exit
process.on('exit', () => {
server.kill();
});
================
File: src/tool-handlers.ts
================
/**
* @file tool-handlers.ts
* @version 1.0.0
*
* Provides handlers for the MCP tools exposed by the Vibe-Coder MCP Server.
* These handlers are registered with the tool registry for consistent handling.
*/
import { z } from 'zod';
import { ToolHandler, toolRegistry } from './registry.js';
import { getFeature, updateFeature } from './storage.js';
import {
getNextClarificationQuestion,
isClarificationComplete,
getClarificationStatus
} from './clarification.js';
import {
generatePRD,
generateImplementationPlan
} from './documentation.js';
import {
createPhase,
updatePhaseStatus,
addTask,
updateTaskStatus
} from './phases.js';
import {
createFeatureObject
} from './utils.js';
import {
validateFeatureId,
validatePhaseId,
validateTaskId,
validateFeaturePhaseTask,
validateRequiredText,
validatePhaseStatusValue
} from './validators.js';
import {
createToolErrorResponse,
featureNotFoundError,
phaseNotFoundError,
taskNotFoundError,
invalidPhaseTransitionError,
clarificationIncompleteError
} from './errors.js';
import { Phase, Task } from './types.js';
// Schema for start_feature_clarification
const StartFeatureClarificationSchema = z.object({
featureName: z.string().min(2).max(100),
initialDescription: z.string().optional().default("")
});
/**
* Start feature clarification handler
*/
const startFeatureClarificationHandler: ToolHandler<z.infer<typeof StartFeatureClarificationSchema>> = async (params) => {
try {
const { featureName, initialDescription } = StartFeatureClarificationSchema.parse(params);
// Create a new feature
const feature = createFeatureObject(featureName, initialDescription);
updateFeature(feature.id, feature);
// Get the first clarification question
const firstQuestion = getNextClarificationQuestion(feature);
return {
content: [{
type: "text",
text: `Feature ID: ${feature.id}\n\nLet's clarify your feature request. ${firstQuestion}`
}]
};
} catch (error) {
if (error instanceof z.ZodError) {
const errorMessage = error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
return createToolErrorResponse(`Validation error: ${errorMessage}`);
}
return createToolErrorResponse(error instanceof Error ? error.message : "Unknown error");
}
};
// Schema for provide_clarification
const ProvideClarificationSchema = z.object({
featureId: z.string().min(1),
question: z.string().min(1),
answer: z.string().min(1)
});
/**
* Provide clarification handler
*/
const provideClarificationHandler: ToolHandler<z.infer<typeof ProvideClarificationSchema>> = async (params) => {
try {
const { featureId, question, answer } = ProvideClarificationSchema.parse(params);
console.log(`\n[CLARIFICATION] Received request for feature ${featureId}\n Question: "${question.substring(0, 50)}..."\n Answer: "${answer.substring(0, 50)}..."`);
// Get the feature
const feature = getFeature(featureId);
if (!feature) {
console.log(`[CLARIFICATION] Feature ID ${featureId} not found`);
return featureNotFoundError(featureId);
}
console.log(`[CLARIFICATION] Found feature: ${feature.name} with ${feature.clarificationResponses.length} existing responses`);
// Add the clarification response to the feature
feature.clarificationResponses.push({
question,
answer,
timestamp: new Date()
});
console.log(`[CLARIFICATION] Added response, now has ${feature.clarificationResponses.length} responses`);
// Save the feature with the updated clarification response
updateFeature(featureId, feature);
// Get the next question or indicate all questions are answered
const nextQuestion = getNextClarificationQuestion(feature);
if (nextQuestion) {
// Check if nextQuestion is a string before using substring
const questionPreview = typeof nextQuestion === 'string'
? nextQuestion.substring(0, 50) + "..."
: "All questions answered";
console.log(`[CLARIFICATION] Returning next question: "${questionPreview}"`);
return {
content: [{
type: "text",
text: `Response recorded. ${nextQuestion}`
}]
};
} else {
// All questions answered
console.log(`[CLARIFICATION] All questions answered`);
return {
content: [{
type: "text",
text: "All clarification questions have been answered. You can now generate a PRD for this feature."
}]
};
}
} catch (error) {
if (error instanceof z.ZodError) {
const errorMessage = error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
return createToolErrorResponse(`Validation error: ${errorMessage}`);
}
return createToolErrorResponse(error instanceof Error ? error.message : "Unknown error");
}
};
// Schema for generate_prd
const GeneratePrdSchema = z.object({
featureId: z.string().min(1)
});
/**
* Generate PRD handler
*/
const generatePrdHandler: ToolHandler<z.infer<typeof GeneratePrdSchema>> = async (params) => {
try {
const { featureId } = GeneratePrdSchema.parse(params);
// Validate feature ID
const featureResult = validateFeatureId(featureId);
if (!featureResult.valid) {
return createToolErrorResponse(featureResult.message);
}
const feature = featureResult.data;
// Check if clarifications are complete
if (!isClarificationComplete(feature)) {
return clarificationIncompleteError(getClarificationStatus(feature));
}
// Generate PRD
const prdDoc = generatePRD(feature);
// Store the document
feature.prdDoc = prdDoc;
updateFeature(featureId, feature);
return {
content: [{
type: "text",
text: `PRD generated for feature ${feature.name}. You can view it using the resource URI: feature://${feature.id}/prd`
}]
};
} catch (error) {
if (error instanceof z.ZodError) {
const errorMessage = error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
return createToolErrorResponse(`Validation error: ${errorMessage}`);
}
return createToolErrorResponse(error instanceof Error ? error.message : "Unknown error");
}
};
// Schema for generate_implementation_plan
const GenerateImplementationPlanSchema = z.object({
featureId: z.string().min(1)
});
/**
* Generate implementation plan handler
*/
const generateImplementationPlanHandler: ToolHandler<z.infer<typeof GenerateImplementationPlanSchema>> = async (params) => {
try {
const { featureId } = GenerateImplementationPlanSchema.parse(params);
// Validate feature ID
const featureResult = validateFeatureId(featureId);
if (!featureResult.valid) {
return createToolErrorResponse(featureResult.message);
}
const feature = featureResult.data;
// Check if clarifications are complete
if (!isClarificationComplete(feature)) {
return clarificationIncompleteError(getClarificationStatus(feature));
}
// Generate the implementation plan
const implDoc = generateImplementationPlan(feature);
// Store the document
feature.implDoc = implDoc;
updateFeature(featureId, feature);
return {
content: [{
type: "text",
text: `Implementation plan generated for feature ${feature.name}. You can view it using the resource URI: feature://${feature.id}/implementation`
}]
};
} catch (error) {
if (error instanceof z.ZodError) {
const errorMessage = error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
return createToolErrorResponse(`Validation error: ${errorMessage}`);
}
return createToolErrorResponse(error instanceof Error ? error.message : "Unknown error");
}
};
// Schema for create_phase
const CreatePhaseSchema = z.object({
featureId: z.string().min(1),
name: z.string().min(2).max(100),
description: z.string().min(1)
});
/**
* Create phase handler
*/
const createPhaseHandler: ToolHandler<z.infer<typeof CreatePhaseSchema>> = async (params) => {
try {
const { featureId, name, description } = CreatePhaseSchema.parse(params);
// Validate feature ID
const featureResult = validateFeatureId(featureId);
if (!featureResult.valid) {
return createToolErrorResponse(featureResult.message);
}
const feature = featureResult.data;
// Create the phase
const phase = createPhase(featureId, name, description);
if (!phase) {
return createToolErrorResponse(`Failed to create phase for feature ${feature.name}`);
}
return {
content: [{
type: "text",
text: `Phase "${name}" created with ID: ${phase.id}`
}]
};
} catch (error) {
if (error instanceof z.ZodError) {
const errorMessage = error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
return createToolErrorResponse(`Validation error: ${errorMessage}`);
}
return createToolErrorResponse(error instanceof Error ? error.message : "Unknown error");
}
};
// Schema for update_phase_status
const UpdatePhaseStatusSchema = z.object({
featureId: z.string().min(1),
phaseId: z.string().min(1),
status: z.enum(["pending", "in_progress", "completed", "reviewed"])
});
/**
* Update phase status handler
*/
const updatePhaseStatusHandler: ToolHandler<z.infer<typeof UpdatePhaseStatusSchema>> = async (params) => {
try {
const { featureId, phaseId, status } = UpdatePhaseStatusSchema.parse(params);
// Validate feature and phase
const validationResult = validateFeaturePhaseTask(featureId, phaseId);
if (!validationResult.valid) {
return createToolErrorResponse(validationResult.message);
}
const { feature, phase } = validationResult.data;
// Validate the status transition
const transitionResult = phase.status !== status;
if (!transitionResult) {
return invalidPhaseTransitionError(phase.status, status);
}
// Update the phase status
const updatedPhase = updatePhaseStatus(featureId, phaseId, status);
return {
content: [{
type: "text",
text: `Phase status updated to "${status}"`
}]
};
} catch (error) {
if (error instanceof z.ZodError) {
const errorMessage = error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
return createToolErrorResponse(`Validation error: ${errorMessage}`);
}
return createToolErrorResponse(error instanceof Error ? error.message : "Unknown error");
}
};
// Schema for add_task
const AddTaskSchema = z.object({
featureId: z.string().min(1),
phaseId: z.string().min(1),
description: z.string().min(3).max(500)
});
/**
* Add task handler
*/
const addTaskHandler: ToolHandler<z.infer<typeof AddTaskSchema>> = async (params) => {
try {
const { featureId, phaseId, description } = AddTaskSchema.parse(params);
// Validate feature and phase
const validationResult = validateFeaturePhaseTask(featureId, phaseId);
if (!validationResult.valid) {
return createToolErrorResponse(validationResult.message);
}
const { feature, phase } = validationResult.data;
// Add the task
const taskId = addTask(featureId, phaseId, description);
return {
content: [{
type: "text",
text: `Task added to phase "${phase.name}" with ID: ${taskId}`
}]
};
} catch (error) {
if (error instanceof z.ZodError) {
const errorMessage = error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
return createToolErrorResponse(`Validation error: ${errorMessage}`);
}
return createToolErrorResponse(error instanceof Error ? error.message : "Unknown error");
}
};
// Schema for update_task_status
const UpdateTaskStatusSchema = z.object({
featureId: z.string().min(1),
phaseId: z.string().min(1),
taskId: z.string().min(1),
completed: z.boolean()
});
/**
* Update task status handler
*/
const updateTaskStatusHandler: ToolHandler<z.infer<typeof UpdateTaskStatusSchema>> = async (params) => {
try {
const { featureId, phaseId, taskId, completed } = UpdateTaskStatusSchema.parse(params);
// Validate feature, phase and task
const validationResult = validateFeaturePhaseTask(featureId, phaseId, taskId);
if (!validationResult.valid) {
return createToolErrorResponse(validationResult.message);
}
const { feature, phase, task } = validationResult.data;
// Update the task status
const updatedTask = updateTaskStatus(featureId, phaseId, taskId, completed);
// Check if all tasks in this phase are now completed
if (completed && phase.tasks.every((t: Task) => t.id === taskId || t.completed)) {
// Auto-advance the phase to 'completed' status
return {
content: [{
type: "text",
text: `Task marked as ${completed ? 'completed' : 'incomplete'}. All tasks in this phase are now complete. The phase "${phase.name}" has been automatically marked as completed.`
}]
};
}
// Check if all tasks are completed and suggest phase update if applicable
let message = `Task status updated to ${completed ? 'completed' : 'not completed'}`;
if (completed && phase.tasks.every((t: Task) => t.id === taskId || t.completed)) {
// All tasks are now completed
message += `. All tasks in phase ${phase.name} are now completed. Consider updating the phase status to 'completed'.`;
}
return {
content: [{
type: "text",
text: message
}]
};
} catch (error) {
if (error instanceof z.ZodError) {
const errorMessage = error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
return createToolErrorResponse(`Validation error: ${errorMessage}`);
}
return createToolErrorResponse(error instanceof Error ? error.message : "Unknown error");
}
};
// Schema for get_next_phase_action
const GetNextPhaseActionSchema = z.object({
featureId: z.string().min(1)
});
/**
* Get next phase action handler
*/
const getNextPhaseActionHandler: ToolHandler<z.infer<typeof GetNextPhaseActionSchema>> = async (params) => {
try {
const { featureId } = GetNextPhaseActionSchema.parse(params);
// Validate feature ID
const featureResult = validateFeatureId(featureId);
if (!featureResult.valid) {
return createToolErrorResponse(featureResult.message);
}
const feature = featureResult.data;
// Find the current active phase (first non-completed/reviewed phase)
const currentPhase = feature.phases.find((p: Phase) => p.status === 'pending' || p.status === 'in_progress');
if (!currentPhase) {
// All phases are completed or reviewed
return {
content: [{
type: "text",
text: 'All phases are completed or reviewed. The feature implementation is done!'
}]
};
}
// Check task completion status
const completedTasks = currentPhase.tasks.filter((t: Task) => t.completed);
const pendingTasks = currentPhase.tasks.filter((t: Task) => !t.completed);
// Determine next action based on phase and task status
let message = '';
if (currentPhase.status === 'pending') {
message = `Phase "${currentPhase.name}" is pending. Start working on this phase by setting its status to "in_progress".`;
} else if (currentPhase.status === 'in_progress') {
if (pendingTasks.length > 0) {
message = `${completedTasks.length}/${currentPhase.tasks.length} tasks are completed in phase "${currentPhase.name}". Continue working on pending tasks.`;
} else if (currentPhase.tasks.length === 0) {
message = `Phase "${currentPhase.name}" has no tasks defined. Add tasks or mark the phase as completed if appropriate.`;
} else {
// All tasks are completed
message = `All tasks in phase "${currentPhase.name}" are completed. Consider marking this phase as completed.`;
}
}
return {
content: [{
type: "text",
text: message
}]
};
} catch (error) {
if (error instanceof z.ZodError) {
const errorMessage = error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
return createToolErrorResponse(`Validation error: ${errorMessage}`);
}
return createToolErrorResponse(error instanceof Error ? error.message : "Unknown error");
}
};
/**
* Register all tool handlers with the tool registry
*/
export function registerToolHandlers() {
toolRegistry.register(
'start_feature_clarification',
startFeatureClarificationHandler,
'Start the clarification process for a new feature',
{
type: "object",
properties: {
featureName: {
type: "string",
description: "Name of the feature"
},
initialDescription: {
type: "string",
description: "Initial description of the feature"
}
},
required: ["featureName"]
},
[
{
featureName: "User Authentication",
initialDescription: "Add login and registration functionality to the application"
},
{
featureName: "Data Export",
initialDescription: "Allow users to export their data in CSV and JSON formats"
}
]
);
toolRegistry.register(
'provide_clarification',
provideClarificationHandler,
'Provide answer to a clarification question',
{
type: "object",
properties: {
featureId: {
type: "string",
description: "ID of the feature"
},
question: {
type: "string",
description: "Clarification question"
},
answer: {
type: "string",
description: "Answer to the clarification question"
}
},
required: ["featureId", "question", "answer"]
},
[
{
featureId: "feature-123",
question: "What problem does this feature solve?",
answer: "This feature solves the problem of users forgetting their passwords by providing a secure password reset flow."
},
{
featureId: "feature-456",
question: "Who are the target users?",
answer: "The target users are administrators who need to manage user accounts and permissions."
}
]
);
toolRegistry.register(
'generate_prd',
generatePrdHandler,
'Generate a PRD document based on clarification responses',
{
type: "object",
properties: {
featureId: {
type: "string",
description: "ID of the feature"
}
},
required: ["featureId"]
},
[
{ featureId: "feature-123" }
]
);
toolRegistry.register(
'generate_implementation_plan',
generateImplementationPlanHandler,
'Generate an implementation plan for a feature based on clarifications and PRD',
{
type: 'object',
properties: {
featureId: {
type: 'string',
description: 'The ID of the feature to generate an implementation plan for'
}
},
required: ['featureId']
}
);
toolRegistry.register(
'create_phase',
createPhaseHandler,
'Create a new development phase for a feature',
{
type: 'object',
properties: {
featureId: {
type: 'string',
description: 'ID of the feature to create a phase for'
},
name: {
type: 'string',
description: 'Name of the phase'
},
description: {
type: 'string',
description: 'Description of the phase'
}
},
required: ['featureId', 'name', 'description']
},
[
{
featureId: "feature-123",
name: "Requirements Analysis",
description: "Gather and analyze requirements for the feature"
},
{
featureId: "feature-123",
name: "Implementation",
description: "Implement the core functionality of the feature"
}
]
);
toolRegistry.register(
'update_phase_status',
updatePhaseStatusHandler,
'Update the status of a development phase',
{
type: 'object',
properties: {
featureId: {
type: 'string',
description: 'ID of the feature containing the phase'
},
phaseId: {
type: 'string',
description: 'ID of the phase to update'
},
status: {
type: 'string',
description: 'New status for the phase (pending, in_progress, completed, reviewed)'
}
},
required: ['featureId', 'phaseId', 'status']
},
[
{
featureId: "feature-123",
phaseId: "phase-456",
status: "in_progress"
},
{
featureId: "feature-123",
phaseId: "phase-456",
status: "completed"
}
]
);
toolRegistry.register(
'add_task',
addTaskHandler,
'Add a task to a development phase',
{
type: 'object',
properties: {
featureId: {
type: 'string',
description: 'ID of the feature containing the phase'
},
phaseId: {
type: 'string',
description: 'ID of the phase to add the task to'
},
description: {
type: 'string',
description: 'Description of the task'
}
},
required: ['featureId', 'phaseId', 'description']
},
[
{
featureId: "feature-123",
phaseId: "phase-456",
description: "Create database migration scripts"
},
{
featureId: "feature-123",
phaseId: "phase-456",
description: "Implement user interface components"
}
]
);
toolRegistry.register(
'update_task_status',
updateTaskStatusHandler,
'Update the completion status of a task',
{
type: 'object',
properties: {
featureId: {
type: 'string',
description: 'ID of the feature containing the phase'
},
phaseId: {
type: 'string',
description: 'ID of the phase containing the task'
},
taskId: {
type: 'string',
description: 'ID of the task to update'
},
completed: {
type: 'boolean',
description: 'Whether the task is completed'
}
},
required: ['featureId', 'phaseId', 'taskId', 'completed']
},
[
{
featureId: "feature-123",
phaseId: "phase-456",
taskId: "task-789",
completed: true
},
{
featureId: "feature-123",
phaseId: "phase-456",
taskId: "task-789",
completed: false
}
]
);
toolRegistry.register(
'get_next_phase_action',
getNextPhaseActionHandler,
'Get guidance on what to do next in the current phase or whether to move to the next phase',
{
type: 'object',
properties: {
featureId: {
type: 'string',
description: 'ID of the feature'
}
},
required: ['featureId']
},
[
{ featureId: "feature-123" }
]
);
}
// Export all handlers for testing or direct usage
export {
startFeatureClarificationHandler,
provideClarificationHandler,
generatePrdHandler,
generateImplementationPlanHandler,
createPhaseHandler,
updatePhaseStatusHandler,
addTaskHandler,
updateTaskStatusHandler,
getNextPhaseActionHandler
};
================
File: src/types.ts
================
/**
* Core data types for the Vibe-Coder MCP Server
*/
/**
* Represents a feature being developed
*/
export type Feature = {
id: string;
name: string;
description: string;
clarificationResponses: ClarificationResponse[];
prd?: string;
prdDoc?: string;
implementationPlan?: string;
implDoc?: string;
phases: Phase[];
createdAt: Date;
updatedAt: Date;
};
/**
* Represents a question and answer pair from the clarification process
*/
export type ClarificationResponse = {
question: string;
answer: string;
timestamp: Date;
};
/**
* Represents a development phase within a feature
*/
export type Phase = {
id: string;
name: string;
description: string;
tasks: Task[];
status: PhaseStatus;
createdAt: Date;
updatedAt: Date;
};
/**
* Possible statuses for a development phase
*/
export type PhaseStatus = "pending" | "in_progress" | "completed" | "reviewed";
/**
* Represents a task within a development phase
*/
export type Task = {
id: string;
description: string;
completed: boolean;
createdAt: Date;
updatedAt: Date;
};
/**
* Storage interface for features
*/
export interface FeatureStorage {
[id: string]: Feature;
}
================
File: src/utils.ts
================
/**
* @file utils.ts
* @version 1.1.0
*
* Utility functions for the Vibe-Coder MCP Server
*/
import { Feature, Phase, Task, PhaseStatus } from './types.js';
import { FeatureId, PhaseId, TaskId, createFeatureId, createPhaseId, createTaskId } from './schemas.js';
/**
* Generate a unique ID for features with proper prefix
* @returns A feature ID string
*/
export function generateFeatureId(): FeatureId {
const randomPart = Math.random().toString(36).substring(2, 10);
return createFeatureId(`feature-${randomPart}`);
}
/**
* Generate a unique ID for phases with proper prefix
* @returns A phase ID string
*/
export function generatePhaseId(): PhaseId {
const randomPart = Math.random().toString(36).substring(2, 10);
return createPhaseId(`phase-${randomPart}`);
}
/**
* Generate a unique ID for tasks with proper prefix
* @returns A task ID string
*/
export function generateTaskId(): TaskId {
const randomPart = Math.random().toString(36).substring(2, 10);
return createTaskId(`task-${randomPart}`);
}
/**
* Legacy ID generator for backward compatibility
* @deprecated Use the typed ID generators instead
* @returns A random string ID
*/
export function generateId(): string {
return Math.random().toString(36).substring(2, 15) +
Math.random().toString(36).substring(2, 15);
}
/**
* Format a date to ISO string without milliseconds
* @param date The date to format
* @returns Formatted date string
*/
export function formatDate(date: Date): string {
return date.toISOString().split('.')[0] + 'Z';
}
/**
* Create a new timestamp
* @returns Current date
*/
export function now(): Date {
return new Date();
}
/**
* Create a default feature object with the given name and description
* @param name The feature name
* @param description The feature description
* @returns A new feature object
*/
export function createFeatureObject(name: string, description: string = ""): Feature {
const timestamp = now();
return {
id: generateFeatureId(),
name,
description,
clarificationResponses: [],
phases: [],
createdAt: timestamp,
updatedAt: timestamp
};
}
/**
* Create a default phase object with the given name and description
* @param name The phase name
* @param description The phase description
* @returns A new phase object
*/
export function createPhaseObject(name: string, description: string): Phase {
const timestamp = now();
return {
id: generatePhaseId(),
name,
description,
tasks: [],
status: "pending" as PhaseStatus,
createdAt: timestamp,
updatedAt: timestamp
};
}
/**
* Create a default task object with the given description
* @param description The task description
* @returns A new task object
*/
export function createTaskObject(description: string): Task {
const timestamp = now();
return {
id: generateTaskId(),
description,
completed: false,
createdAt: timestamp,
updatedAt: timestamp
};
}
/**
* Validate if a status is a valid phase status
* @param status The status to validate
* @returns True if valid, false otherwise
*/
export function isValidPhaseStatus(status: string): boolean {
return ['pending', 'in_progress', 'completed', 'reviewed'].includes(status);
}
/**
* Generate a detailed progress summary for a feature
* @param feature The feature to generate a summary for
* @returns A formatted string with the feature's progress details
*/
export function generateFeatureProgressSummary(feature: Feature): string {
const totalPhases = feature.phases.length;
const completedPhases = feature.phases.filter(p => p.status === 'completed' || p.status === 'reviewed').length;
const inProgressPhases = feature.phases.filter(p => p.status === 'in_progress').length;
const totalTasks = feature.phases.reduce((acc, phase) => acc + phase.tasks.length, 0);
const completedTasks = feature.phases.reduce(
(acc, phase) => acc + phase.tasks.filter(t => t.completed).length, 0
);
const phaseProgress = totalPhases > 0
? Math.round((completedPhases / totalPhases) * 100)
: 0;
const taskProgress = totalTasks > 0
? Math.round((completedTasks / totalTasks) * 100)
: 0;
let summary = `
# Feature Progress: ${feature.name}
## Overview
- Feature ID: ${feature.id}
- Created: ${feature.createdAt.toISOString()}
- Last Updated: ${feature.updatedAt.toISOString()}
- Description: ${feature.description}
## Progress Summary
- Phases: ${completedPhases}/${totalPhases} completed (${phaseProgress}%)
- Tasks: ${completedTasks}/${totalTasks} completed (${taskProgress}%)
- Phases in Progress: ${inProgressPhases}
## Phase Details
`;
if (totalPhases === 0) {
summary += "\nNo phases defined for this feature yet.";
} else {
feature.phases.forEach(phase => {
const phaseTasks = phase.tasks.length;
const phaseCompletedTasks = phase.tasks.filter(t => t.completed).length;
const phaseTaskProgress = phaseTasks > 0
? Math.round((phaseCompletedTasks / phaseTasks) * 100)
: 0;
summary += `
### ${phase.name} (${phase.status})
- ID: ${phase.id}
- Progress: ${phaseCompletedTasks}/${phaseTasks} tasks (${phaseTaskProgress}%)
- Description: ${phase.description}
Tasks:
${phase.tasks.map(task => `- [${task.completed ? 'x' : ' '}] ${task.description}`).join('\n')}
`;
});
}
return summary;
}
================
File: src/validators.ts
================
/**
* @file validators.ts
* @version 1.0.0
*
* Provides validation utilities for the Vibe-Coder MCP Server tools.
* These validators ensure that tool inputs are valid and provide consistent
* error handling across all tools.
*/
import { Feature, Phase, Task, PhaseStatus } from './types.js';
import { getFeature } from './storage.js';
import { isValidPhaseStatus } from './utils.js';
/**
* Standard validation result type
*/
export type ValidationResult = {
valid: boolean;
message: string;
data?: any; // Optional validated data
};
/**
* Validate feature ID and return the feature if valid
* @param featureId The feature ID to validate
* @returns Validation result with feature in data if valid
*/
export function validateFeatureId(featureId: string): ValidationResult {
// Check if feature ID is provided
if (!featureId || featureId.trim() === '') {
return {
valid: false,
message: 'Feature ID is required'
};
}
// Check if feature exists
const feature = getFeature(featureId);
if (!feature) {
return {
valid: false,
message: `Feature with ID ${featureId} not found`
};
}
return {
valid: true,
message: 'Feature is valid',
data: feature
};
}
/**
* Validate phase ID in the context of a feature
* @param feature The feature containing the phase
* @param phaseId The phase ID to validate
* @returns Validation result with phase in data if valid
*/
export function validatePhaseId(feature: Feature, phaseId: string): ValidationResult {
// Check if phase ID is provided
if (!phaseId || phaseId.trim() === '') {
return {
valid: false,
message: 'Phase ID is required'
};
}
// Check if phase exists in feature
const phase = feature.phases.find(p => p.id === phaseId);
if (!phase) {
return {
valid: false,
message: `Phase with ID ${phaseId} not found in feature ${feature.name}`
};
}
return {
valid: true,
message: 'Phase is valid',
data: phase
};
}
/**
* Validate task ID in the context of a phase
* @param phase The phase containing the task
* @param taskId The task ID to validate
* @returns Validation result with task in data if valid
*/
export function validateTaskId(phase: Phase, taskId: string): ValidationResult {
// Check if task ID is provided
if (!taskId || taskId.trim() === '') {
return {
valid: false,
message: 'Task ID is required'
};
}
// Check if task exists in phase
const task = phase.tasks.find(t => t.id === taskId);
if (!task) {
return {
valid: false,
message: `Task with ID ${taskId} not found in phase ${phase.name}`
};
}
return {
valid: true,
message: 'Task is valid',
data: task
};
}
/**
* Validate phase status
* @param status The status to validate
* @returns Validation result
*/
export function validatePhaseStatusValue(status: string): ValidationResult {
if (!status || status.trim() === '') {
return {
valid: false,
message: 'Phase status is required'
};
}
if (!isValidPhaseStatus(status)) {
return {
valid: false,
message: `Invalid phase status: ${status}. Valid values are: pending, in_progress, completed, reviewed`
};
}
return {
valid: true,
message: 'Phase status is valid',
data: status as PhaseStatus
};
}
/**
* Validate required text field
* @param value The text value
* @param fieldName The name of the field for error messages
* @param minLength Minimum allowed length
* @param maxLength Maximum allowed length
* @returns Validation result
*/
export function validateRequiredText(
value: string,
fieldName: string,
minLength: number = 1,
maxLength: number = 1000
): ValidationResult {
if (!value || value.trim() === '') {
return {
valid: false,
message: `${fieldName} is required`
};
}
if (value.length < minLength) {
return {
valid: false,
message: `${fieldName} must be at least ${minLength} characters`
};
}
if (value.length > maxLength) {
return {
valid: false,
message: `${fieldName} must be no more than ${maxLength} characters`
};
}
return {
valid: true,
message: `${fieldName} is valid`,
data: value.trim()
};
}
/**
* Validate feature, phase, and task IDs together
* @param featureId Feature ID
* @param phaseId Phase ID
* @param taskId Task ID (optional)
* @returns Validation result with feature, phase, and task in data if valid
*/
export function validateFeaturePhaseTask(
featureId: string,
phaseId: string,
taskId?: string
): ValidationResult {
// Validate feature
const featureResult = validateFeatureId(featureId);
if (!featureResult.valid) {
return featureResult;
}
// Validate phase
const phaseResult = validatePhaseId(featureResult.data, phaseId);
if (!phaseResult.valid) {
return phaseResult;
}
// If taskId is provided, validate it
if (taskId) {
const taskResult = validateTaskId(phaseResult.data, taskId);
if (!taskResult.valid) {
return taskResult;
}
return {
valid: true,
message: 'Feature, phase, and task are valid',
data: {
feature: featureResult.data,
phase: phaseResult.data,
task: taskResult.data
}
};
}
return {
valid: true,
message: 'Feature and phase are valid',
data: {
feature: featureResult.data,
phase: phaseResult.data
}
};
}
================
File: .gitignore
================
node_modules/
build/
*.log
.env*
================
File: debug.js
================
#!/usr/bin/env node
// This file is just for inspecting the features state
// Since we can't access the runtime state directly,
// we'll examine how the clarification functions work
import { getNextClarificationQuestion, DEFAULT_CLARIFICATION_QUESTIONS } from './build/clarification.js';
console.log('Default questions:', DEFAULT_CLARIFICATION_QUESTIONS);
// Test the function with a mock feature
const mockFeature = {
id: 'test',
clarificationResponses: []
};
console.log('Initial question:', getNextClarificationQuestion(mockFeature));
// Add a response and check next question
mockFeature.clarificationResponses.push({
question: DEFAULT_CLARIFICATION_QUESTIONS[0],
answer: 'Test answer',
timestamp: new Date()
});
console.log('After 1 response, next question:', getNextClarificationQuestion(mockFeature));
// Add another response
mockFeature.clarificationResponses.push({
question: DEFAULT_CLARIFICATION_QUESTIONS[1],
answer: 'Test answer 2',
timestamp: new Date()
});
console.log('After 2 responses, next question:', getNextClarificationQuestion(mockFeature));
================
File: MCP-docs.txt
================
# Example Clients
Source: https://modelcontextprotocol.io/clients
A list of applications that support MCP integrations
This page provides an overview of applications that support the Model Context Protocol (MCP). Each client may support different MCP features, allowing for varying levels of integration with MCP servers.
## Feature support matrix
| Client | [Resources] | [Prompts] | [Tools] | [Sampling] | Roots | Notes |
| ------------------------------------ | ----------- | --------- | ------- | ---------- | ----- | ------------------------------------------------------------------ |
| [Claude Desktop App][Claude] | ✅ | ✅ | ✅ | ❌ | ❌ | Full support for all MCP features |
| [5ire][5ire] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
| [BeeAI Framework][BeeAI Framework] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools in agentic workflows. |
| [Cline][Cline] | ✅ | ❌ | ✅ | ❌ | ❌ | Supports tools and resources. |
| [Continue][Continue] | ✅ | ✅ | ✅ | ❌ | ❌ | Full support for all MCP features |
| [Cursor][Cursor] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
| [Emacs Mcp][Mcp.el] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools in Emacs. |
| [Firebase Genkit][Genkit] | ⚠️ | ✅ | ✅ | ❌ | ❌ | Supports resource list and lookup through tools. |
| [GenAIScript][GenAIScript] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
| [Goose][Goose] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
| [LibreChat][LibreChat] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools for Agents |
| [mcp-agent][mcp-agent] | ❌ | ❌ | ✅ | ⚠️ | ❌ | Supports tools, server connection management, and agent workflows. |
| [oterm][oterm] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
| [Roo Code][Roo Code] | ✅ | ❌ | ✅ | ❌ | ❌ | Supports tools and resources. |
| [Sourcegraph Cody][Cody] | ✅ | ❌ | ❌ | ❌ | ❌ | Supports resources through OpenCTX |
| [Superinterface][Superinterface] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools |
| [TheiaAI/TheiaIDE][TheiaAI/TheiaIDE] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools for Agents in Theia AI and the AI-powered Theia IDE |
| [Windsurf Editor][Windsurf] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools with AI Flow for collaborative development. |
| [Zed][Zed] | ❌ | ✅ | ❌ | ❌ | ❌ | Prompts appear as slash commands |
| [SpinAI][SpinAI] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools for Typescript AI Agents |
| [OpenSumi][OpenSumi] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools in OpenSumi |
| [Daydreams Agents][Daydreams] | ✅ | ✅ | ✅ | ❌ | ❌ | Support for drop in Servers to Daydreams agents |
[Claude]: https://claude.ai/download
[Cursor]: https://cursor.com
[Zed]: https://zed.dev
[Cody]: https://sourcegraph.com/cody
[Genkit]: https://github.com/firebase/genkit
[Continue]: https://github.com/continuedev/continue
[GenAIScript]: https://microsoft.github.io/genaiscript/reference/scripts/mcp-tools/
[Cline]: https://github.com/cline/cline
[LibreChat]: https://github.com/danny-avila/LibreChat
[TheiaAI/TheiaIDE]: https://eclipsesource.com/blogs/2024/12/19/theia-ide-and-theia-ai-support-mcp/
[Superinterface]: https://superinterface.ai
[5ire]: https://github.com/nanbingxyz/5ire
[BeeAI Framework]: https://i-am-bee.github.io/beeai-framework
[mcp-agent]: https://github.com/lastmile-ai/mcp-agent
[Mcp.el]: https://github.com/lizqwerscott/mcp.el
[Roo Code]: https://roocode.com
[Goose]: https://block.github.io/goose/docs/goose-architecture/#interoperability-with-extensions
[Windsurf]: https://codeium.com/windsurf
[Daydreams]: https://github.com/daydreamsai/daydreams
[SpinAI]: https://spinai.dev
[OpenSumi]: https://github.com/opensumi/core
[oterm]: https://github.com/ggozad/oterm
[Resources]: https://modelcontextprotocol.io/docs/concepts/resources
[Prompts]: https://modelcontextprotocol.io/docs/concepts/prompts
[Tools]: https://modelcontextprotocol.io/docs/concepts/tools
[Sampling]: https://modelcontextprotocol.io/docs/concepts/sampling
## Client details
### Claude Desktop App
The Claude desktop application provides comprehensive support for MCP, enabling deep integration with local tools and data sources.
**Key features:**
* Full support for resources, allowing attachment of local files and data
* Support for prompt templates
* Tool integration for executing commands and scripts
* Local server connections for enhanced privacy and security
> ⓘ Note: The Claude.ai web application does not currently support MCP. MCP features are only available in the desktop application.
### 5ire
[5ire](https://github.com/nanbingxyz/5ire) is an open source cross-platform desktop AI assistant that supports tools through MCP servers.
**Key features:**
* Built-in MCP servers can be quickly enabled and disabled.
* Users can add more servers by modifying the configuration file.
* It is open-source and user-friendly, suitable for beginners.
* Future support for MCP will be continuously improved.
### BeeAI Framework
[BeeAI Framework](https://i-am-bee.github.io/beeai-framework) is an open-source framework for building, deploying, and serving powerful agentic workflows at scale. The framework includes the **MCP Tool**, a native feature that simplifies the integration of MCP servers into agentic workflows.
**Key features:**
* Seamlessly incorporate MCP tools into agentic workflows.
* Quickly instantiate framework-native tools from connected MCP client(s).
* Planned future support for agentic MCP capabilities.
**Learn more:**
* [Example of using MCP tools in agentic workflow](https://i-am-bee.github.io/beeai-framework/#/typescript/tools?id=using-the-mcptool-class)
### Cline
[Cline](https://github.com/cline/cline) is an autonomous coding agent in VS Code that edits files, runs commands, uses a browser, and more–with your permission at each step.
**Key features:**
* Create and add tools through natural language (e.g. "add a tool that searches the web")
* Share custom MCP servers Cline creates with others via the `~/Documents/Cline/MCP` directory
* Displays configured MCP servers along with their tools, resources, and any error logs
### Continue
[Continue](https://github.com/continuedev/continue) is an open-source AI code assistant, with built-in support for all MCP features.
**Key features**
* Type "@" to mention MCP resources
* Prompt templates surface as slash commands
* Use both built-in and MCP tools directly in chat
* Supports VS Code and JetBrains IDEs, with any LLM
### Cursor
[Cursor](https://docs.cursor.com/advanced/model-context-protocol) is an AI code editor.
**Key Features**:
* Support for MCP tools in Cursor Composer
* Support for both STDIO and SSE
### Emacs Mcp
[Emacs Mcp](https://github.com/lizqwerscott/mcp.el) is an Emacs client designed to interface with MCP servers, enabling seamless connections and interactions. It provides MCP tool invocation support for AI plugins like [gptel](https://github.com/karthink/gptel) and [llm](https://github.com/ahyatt/llm), adhering to Emacs' standard tool invocation format. This integration enhances the functionality of AI tools within the Emacs ecosystem.
**Key features:**
* Provides MCP tool support for Emacs.
### Firebase Genkit
[Genkit](https://github.com/firebase/genkit) is Firebase's SDK for building and integrating GenAI features into applications. The [genkitx-mcp](https://github.com/firebase/genkit/tree/main/js/plugins/mcp) plugin enables consuming MCP servers as a client or creating MCP servers from Genkit tools and prompts.
**Key features:**
* Client support for tools and prompts (resources partially supported)
* Rich discovery with support in Genkit's Dev UI playground
* Seamless interoperability with Genkit's existing tools and prompts
* Works across a wide variety of GenAI models from top providers
### GenAIScript
Programmatically assemble prompts for LLMs using [GenAIScript](https://microsoft.github.io/genaiscript/) (in JavaScript). Orchestrate LLMs, tools, and data in JavaScript.
**Key features:**
* JavaScript toolbox to work with prompts
* Abstraction to make it easy and productive
* Seamless Visual Studio Code integration
### Goose
[Goose](https://github.com/block/goose) is an open source AI agent that supercharges your software development by automating coding tasks.
**Key features:**
* Expose MCP functionality to Goose through tools.
* MCPs can be installed directly via the [extensions directory](https://block.github.io/goose/v1/extensions/), CLI, or UI.
* Goose allows you to extend its functionality by [building your own MCP servers](https://block.github.io/goose/docs/tutorials/custom-extensions).
* Includes built-in tools for development, web scraping, automation, memory, and integrations with JetBrains and Google Drive.
### LibreChat
[LibreChat](https://github.com/danny-avila/LibreChat) is an open-source, customizable AI chat UI that supports multiple AI providers, now including MCP integration.
**Key features:**
* Extend current tool ecosystem, including [Code Interpreter](https://www.librechat.ai/docs/features/code_interpreter) and Image generation tools, through MCP servers
* Add tools to customizable [Agents](https://www.librechat.ai/docs/features/agents), using a variety of LLMs from top providers
* Open-source and self-hostable, with secure multi-user support
* Future roadmap includes expanded MCP feature support
### mcp-agent
[mcp-agent] is a simple, composable framework to build agents using Model Context Protocol.
**Key features:**
* Automatic connection management of MCP servers.
* Expose tools from multiple servers to an LLM.
* Implements every pattern defined in [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents).
* Supports workflow pause/resume signals, such as waiting for human feedback.
### oterm
[oterm] is a terminal client for Ollama allowing users to create chats/agents.
**Key features:**
* Support for multiple fully customizable chat sessions with Ollama connected with tools.
* Support for MCP tools.
### Roo Code
[Roo Code](https://roocode.com) enables AI coding assistance via MCP.
**Key features:**
* Support for MCP tools and resources
* Integration with development workflows
* Extensible AI capabilities
### Sourcegraph Cody
[Cody](https://openctx.org/docs/providers/modelcontextprotocol) is Sourcegraph's AI coding assistant, which implements MCP through OpenCTX.
**Key features:**
* Support for MCP resources
* Integration with Sourcegraph's code intelligence
* Uses OpenCTX as an abstraction layer
* Future support planned for additional MCP features
### SpinAI
[SpinAI](https://spinai.dev) is an open-source TypeScript framework for building observable AI agents. The framework provides native MCP compatibility, allowing agents to seamlessly integrate with MCP servers and tools.
**Key features:**
* Built-in MCP compatibility for AI agents
* Open-source TypeScript framework
* Observable agent architecture
* Native support for MCP tools integration
### Superinterface
[Superinterface](https://superinterface.ai) is AI infrastructure and a developer platform to build in-app AI assistants with support for MCP, interactive components, client-side function calling and more.
**Key features:**
* Use tools from MCP servers in assistants embedded via React components or script tags
* SSE transport support
* Use any AI model from any AI provider (OpenAI, Anthropic, Ollama, others)
### TheiaAI/TheiaIDE
[Theia AI](https://eclipsesource.com/blogs/2024/10/07/introducing-theia-ai/) is a framework for building AI-enhanced tools and IDEs. The [AI-powered Theia IDE](https://eclipsesource.com/blogs/2024/10/08/introducting-ai-theia-ide/) is an open and flexible development environment built on Theia AI.
**Key features:**
* **Tool Integration**: Theia AI enables AI agents, including those in the Theia IDE, to utilize MCP servers for seamless tool interaction.
* **Customizable Prompts**: The Theia IDE allows users to define and adapt prompts, dynamically integrating MCP servers for tailored workflows.
* **Custom agents**: The Theia IDE supports creating custom agents that leverage MCP capabilities, enabling users to design dedicated workflows on the fly.
Theia AI and Theia IDE's MCP integration provide users with flexibility, making them powerful platforms for exploring and adapting MCP.
**Learn more:**
* [Theia IDE and Theia AI MCP Announcement](https://eclipsesource.com/blogs/2024/12/19/theia-ide-and-theia-ai-support-mcp/)
* [Download the AI-powered Theia IDE](https://theia-ide.org/)
### Windsurf Editor
[Windsurf Editor](https://codeium.com/windsurf) is an agentic IDE that combines AI assistance with developer workflows. It features an innovative AI Flow system that enables both collaborative and independent AI interactions while maintaining developer control.
**Key features:**
* Revolutionary AI Flow paradigm for human-AI collaboration
* Intelligent code generation and understanding
* Rich development tools with multi-model support
### Zed
[Zed](https://zed.dev/docs/assistant/model-context-protocol) is a high-performance code editor with built-in MCP support, focusing on prompt templates and tool integration.
**Key features:**
* Prompt templates surface as slash commands in the editor
* Tool integration for enhanced coding workflows
* Tight integration with editor features and workspace context
* Does not support MCP resources
### OpenSumi
[OpenSumi](https://github.com/opensumi/core) is a framework helps you quickly build AI Native IDE products.
**Key features:**
* Supports MCP tools in OpenSumi
* Supports built-in IDE MCP servers and custom MCP servers
### Daydreams
[Daydreams](https://github.com/daydreamsai/daydreams) is a generative agent framework for executing anything onchain
**Key features:**
* Supports MCP Servers in config
* Exposes MCP Client
## Adding MCP support to your application
If you've added MCP support to your application, we encourage you to submit a pull request to add it to this list. MCP integration can provide your users with powerful contextual AI capabilities and make your application part of the growing MCP ecosystem.
Benefits of adding MCP support:
* Enable users to bring their own context and tools
* Join a growing ecosystem of interoperable AI applications
* Provide users with flexible integration options
* Support local-first AI workflows
To get started with implementing MCP in your application, check out our [Python](https://github.com/modelcontextprotocol/python-sdk) or [TypeScript SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
## Updates and corrections
This list is maintained by the community. If you notice any inaccuracies or would like to update information about MCP support in your application, please submit a pull request or [open an issue in our documentation repository](https://github.com/modelcontextprotocol/docs/issues).
# Contributing
Source: https://modelcontextprotocol.io/development/contributing
How to participate in Model Context Protocol development
We welcome contributions from the community! Please review our [contributing guidelines](https://github.com/modelcontextprotocol/.github/blob/main/CONTRIBUTING.md) for details on how to submit changes.
All contributors must adhere to our [Code of Conduct](https://github.com/modelcontextprotocol/.github/blob/main/CODE_OF_CONDUCT.md).
For questions and discussions, please use [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions).
# Roadmap
Source: https://modelcontextprotocol.io/development/roadmap
Our plans for evolving Model Context Protocol (H1 2025)
The Model Context Protocol is rapidly evolving. This page outlines our current thinking on key priorities and future direction for **the first half of 2025**, though these may change significantly as the project develops.
<Note>The ideas presented here are not commitments—we may solve these challenges differently than described, or some may not materialize at all. This is also not an *exhaustive* list; we may incorporate work that isn't mentioned here.</Note>
We encourage community participation! Each section links to relevant discussions where you can learn more and contribute your thoughts.
## Remote MCP Support
Our top priority is improving [remote MCP connections](https://github.com/modelcontextprotocol/specification/discussions/112), allowing clients to securely connect to MCP servers over the internet. Key initiatives include:
* [**Authentication & Authorization**](https://github.com/modelcontextprotocol/specification/discussions/64): Adding standardized auth capabilities, particularly focused on OAuth 2.0 support.
* [**Service Discovery**](https://github.com/modelcontextprotocol/specification/discussions/69): Defining how clients can discover and connect to remote MCP servers.
* [**Stateless Operations**](https://github.com/modelcontextprotocol/specification/discussions/102): Thinking about whether MCP could encompass serverless environments too, where they will need to be mostly stateless.
## Reference Implementations
To help developers build with MCP, we want to offer documentation for:
* **Client Examples**: Comprehensive reference client implementation(s), demonstrating all protocol features
* **Protocol Drafting**: Streamlined process for proposing and incorporating new protocol features
## Distribution & Discovery
Looking ahead, we're exploring ways to make MCP servers more accessible. Some areas we may investigate include:
* **Package Management**: Standardized packaging format for MCP servers
* **Installation Tools**: Simplified server installation across MCP clients
* **Sandboxing**: Improved security through server isolation
* **Server Registry**: A common directory for discovering available MCP servers
## Agent Support
We're expanding MCP's capabilities for [complex agentic workflows](https://github.com/modelcontextprotocol/specification/discussions/111), particularly focusing on:
* [**Hierarchical Agent Systems**](https://github.com/modelcontextprotocol/specification/discussions/94): Improved support for trees of agents through namespacing and topology awareness.
* [**Interactive Workflows**](https://github.com/modelcontextprotocol/specification/issues/97): Better handling of user permissions and information requests across agent hierarchies, and ways to send output to users instead of models.
* [**Streaming Results**](https://github.com/modelcontextprotocol/specification/issues/117): Real-time updates from long-running agent operations.
## Broader Ecosystem
We're also invested in:
* **Community-Led Standards Development**: Fostering a collaborative ecosystem where all AI providers can help shape MCP as an open standard through equal participation and shared governance, ensuring it meets the needs of diverse AI applications and use cases.
* [**Additional Modalities**](https://github.com/modelcontextprotocol/specification/discussions/88): Expanding beyond text to support audio, video, and other formats.
* \[**Standardization**] Considering standardization through a standardization body.
## Get Involved
We welcome community participation in shaping MCP's future. Visit our [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions) to join the conversation and contribute your ideas.
# What's New
Source: https://modelcontextprotocol.io/development/updates
The latest updates and improvements to MCP
<Update label="2025-02-14" description="Java SDK released">
* We're excited to announce that the Java SDK developed by Spring AI at VMware Tanzu is now
the official [Java SDK](https://github.com/modelcontextprotocol/java-sdk) for MCP.
This joins our existing Kotlin SDK in our growing list of supported languages.
The Spring AI team will maintain the SDK as an integral part of the Model Context Protocol
organization. We're thrilled to welcome them to the MCP community!
</Update>
<Update label="2025-01-27" description="Python SDK 1.2.1">
* Version [1.2.1](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.2.1) of the MCP Python SDK has been released,
delivering important stability improvements and bug fixes.
</Update>
<Update label="2025-01-18" description="SDK and Server Improvements">
* Simplified, express-like API in the [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
* Added 8 new clients to the [clients page](https://modelcontextprotocol.io/clients)
</Update>
<Update label="2025-01-03" description="SDK and Server Improvements">
* FastMCP API in the [Python SDK](https://github.com/modelcontextprotocol/python-sdk)
* Dockerized MCP servers in the [servers repo](https://github.com/modelcontextprotocol/servers)
</Update>
<Update label="2024-12-21" description="Kotlin SDK released">
* Jetbrains released a Kotlin SDK for MCP!
* For a sample MCP Kotlin server, check out [this repository](https://github.com/modelcontextprotocol/kotlin-sdk/tree/main/samples/kotlin-mcp-server)
</Update>
# Core architecture
Source: https://modelcontextprotocol.io/docs/concepts/architecture
Understand how MCP connects clients, servers, and LLMs
The Model Context Protocol (MCP) is built on a flexible, extensible architecture that enables seamless communication between LLM applications and integrations. This document covers the core architectural components and concepts.
## Overview
MCP follows a client-server architecture where:
* **Hosts** are LLM applications (like Claude Desktop or IDEs) that initiate connections
* **Clients** maintain 1:1 connections with servers, inside the host application
* **Servers** provide context, tools, and prompts to clients
```mermaid
flowchart LR
subgraph "Host"
client1[MCP Client]
client2[MCP Client]
end
subgraph "Server Process"
server1[MCP Server]
end
subgraph "Server Process"
server2[MCP Server]
end
client1 <-->|Transport Layer| server1
client2 <-->|Transport Layer| server2
```
## Core components
### Protocol layer
The protocol layer handles message framing, request/response linking, and high-level communication patterns.
<Tabs>
<Tab title="TypeScript">
```typescript
class Protocol<Request, Notification, Result> {
// Handle incoming requests
setRequestHandler<T>(schema: T, handler: (request: T, extra: RequestHandlerExtra) => Promise<Result>): void
// Handle incoming notifications
setNotificationHandler<T>(schema: T, handler: (notification: T) => Promise<void>): void
// Send requests and await responses
request<T>(request: Request, schema: T, options?: RequestOptions): Promise<T>
// Send one-way notifications
notification(notification: Notification): Promise<void>
}
```
</Tab>
<Tab title="Python">
```python
class Session(BaseSession[RequestT, NotificationT, ResultT]):
async def send_request(
self,
request: RequestT,
result_type: type[Result]
) -> Result:
"""
Send request and wait for response. Raises McpError if response contains error.
"""
# Request handling implementation
async def send_notification(
self,
notification: NotificationT
) -> None:
"""Send one-way notification that doesn't expect response."""
# Notification handling implementation
async def _received_request(
self,
responder: RequestResponder[ReceiveRequestT, ResultT]
) -> None:
"""Handle incoming request from other side."""
# Request handling implementation
async def _received_notification(
self,
notification: ReceiveNotificationT
) -> None:
"""Handle incoming notification from other side."""
# Notification handling implementation
```
</Tab>
</Tabs>
Key classes include:
* `Protocol`
* `Client`
* `Server`
### Transport layer
The transport layer handles the actual communication between clients and servers. MCP supports multiple transport mechanisms:
1. **Stdio transport**
* Uses standard input/output for communication
* Ideal for local processes
2. **HTTP with SSE transport**
* Uses Server-Sent Events for server-to-client messages
* HTTP POST for client-to-server messages
All transports use [JSON-RPC](https://www.jsonrpc.org/) 2.0 to exchange messages. See the [specification](https://spec.modelcontextprotocol.io) for detailed information about the Model Context Protocol message format.
### Message types
MCP has these main types of messages:
1. **Requests** expect a response from the other side:
```typescript
interface Request {
method: string;
params?: { ... };
}
```
2. **Results** are successful responses to requests:
```typescript
interface Result {
[key: string]: unknown;
}
```
3. **Errors** indicate that a request failed:
```typescript
interface Error {
code: number;
message: string;
data?: unknown;
}
```
4. **Notifications** are one-way messages that don't expect a response:
```typescript
interface Notification {
method: string;
params?: { ... };
}
```
## Connection lifecycle
### 1. Initialization
```mermaid
sequenceDiagram
participant Client
participant Server
Client->>Server: initialize request
Server->>Client: initialize response
Client->>Server: initialized notification
Note over Client,Server: Connection ready for use
```
1. Client sends `initialize` request with protocol version and capabilities
2. Server responds with its protocol version and capabilities
3. Client sends `initialized` notification as acknowledgment
4. Normal message exchange begins
### 2. Message exchange
After initialization, the following patterns are supported:
* **Request-Response**: Client or server sends requests, the other responds
* **Notifications**: Either party sends one-way messages
### 3. Termination
Either party can terminate the connection:
* Clean shutdown via `close()`
* Transport disconnection
* Error conditions
## Error handling
MCP defines these standard error codes:
```typescript
enum ErrorCode {
// Standard JSON-RPC error codes
ParseError = -32700,
InvalidRequest = -32600,
MethodNotFound = -32601,
InvalidParams = -32602,
InternalError = -32603
}
```
SDKs and applications can define their own error codes above -32000.
Errors are propagated through:
* Error responses to requests
* Error events on transports
* Protocol-level error handlers
## Implementation example
Here's a basic example of implementing an MCP server:
<Tabs>
<Tab title="TypeScript">
```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = new Server({
name: "example-server",
version: "1.0.0"
}, {
capabilities: {
resources: {}
}
});
// Handle requests
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: "example://resource",
name: "Example Resource"
}
]
};
});
// Connect transport
const transport = new StdioServerTransport();
await server.connect(transport);
```
</Tab>
<Tab title="Python">
```python
import asyncio
import mcp.types as types
from mcp.server import Server
from mcp.server.stdio import stdio_server
app = Server("example-server")
@app.list_resources()
async def list_resources() -> list[types.Resource]:
return [
types.Resource(
uri="example://resource",
name="Example Resource"
)
]
async def main():
async with stdio_server() as streams:
await app.run(
streams[0],
streams[1],
app.create_initialization_options()
)
if __name__ == "__main__":
asyncio.run(main)
```
</Tab>
</Tabs>
## Best practices
### Transport selection
1. **Local communication**
* Use stdio transport for local processes
* Efficient for same-machine communication
* Simple process management
2. **Remote communication**
* Use SSE for scenarios requiring HTTP compatibility
* Consider security implications including authentication and authorization
### Message handling
1. **Request processing**
* Validate inputs thoroughly
* Use type-safe schemas
* Handle errors gracefully
* Implement timeouts
2. **Progress reporting**
* Use progress tokens for long operations
* Report progress incrementally
* Include total progress when known
3. **Error management**
* Use appropriate error codes
* Include helpful error messages
* Clean up resources on errors
## Security considerations
1. **Transport security**
* Use TLS for remote connections
* Validate connection origins
* Implement authentication when needed
2. **Message validation**
* Validate all incoming messages
* Sanitize inputs
* Check message size limits
* Verify JSON-RPC format
3. **Resource protection**
* Implement access controls
* Validate resource paths
* Monitor resource usage
* Rate limit requests
4. **Error handling**
* Don't leak sensitive information
* Log security-relevant errors
* Implement proper cleanup
* Handle DoS scenarios
## Debugging and monitoring
1. **Logging**
* Log protocol events
* Track message flow
* Monitor performance
* Record errors
2. **Diagnostics**
* Implement health checks
* Monitor connection state
* Track resource usage
* Profile performance
3. **Testing**
* Test different transports
* Verify error handling
* Check edge cases
* Load test servers
# Prompts
Source: https://modelcontextprotocol.io/docs/concepts/prompts
Create reusable prompt templates and workflows
Prompts enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a powerful way to standardize and share common LLM interactions.
<Note>
Prompts are designed to be **user-controlled**, meaning they are exposed from servers to clients with the intention of the user being able to explicitly select them for use.
</Note>
## Overview
Prompts in MCP are predefined templates that can:
* Accept dynamic arguments
* Include context from resources
* Chain multiple interactions
* Guide specific workflows
* Surface as UI elements (like slash commands)
## Prompt structure
Each prompt is defined with:
```typescript
{
name: string; // Unique identifier for the prompt
description?: string; // Human-readable description
arguments?: [ // Optional list of arguments
{
name: string; // Argument identifier
description?: string; // Argument description
required?: boolean; // Whether argument is required
}
]
}
```
## Discovering prompts
Clients can discover available prompts through the `prompts/list` endpoint:
```typescript
// Request
{
method: "prompts/list"
}
// Response
{
prompts: [
{
name: "analyze-code",
description: "Analyze code for potential improvements",
arguments: [
{
name: "language",
description: "Programming language",
required: true
}
]
}
]
}
```
## Using prompts
To use a prompt, clients make a `prompts/get` request:
````typescript
// Request
{
method: "prompts/get",
params: {
name: "analyze-code",
arguments: {
language: "python"
}
}
}
// Response
{
description: "Analyze Python code for potential improvements",
messages: [
{
role: "user",
content: {
type: "text",
text: "Please analyze the following Python code for potential improvements:\n\n```python\ndef calculate_sum(numbers):\n total = 0\n for num in numbers:\n total = total + num\n return total\n\nresult = calculate_sum([1, 2, 3, 4, 5])\nprint(result)\n```"
}
}
]
}
````
## Dynamic prompts
Prompts can be dynamic and include:
### Embedded resource context
```json
{
"name": "analyze-project",
"description": "Analyze project logs and code",
"arguments": [
{
"name": "timeframe",
"description": "Time period to analyze logs",
"required": true
},
{
"name": "fileUri",
"description": "URI of code file to review",
"required": true
}
]
}
```
When handling the `prompts/get` request:
```json
{
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "Analyze these system logs and the code file for any issues:"
}
},
{
"role": "user",
"content": {
"type": "resource",
"resource": {
"uri": "logs://recent?timeframe=1h",
"text": "[2024-03-14 15:32:11] ERROR: Connection timeout in network.py:127\n[2024-03-14 15:32:15] WARN: Retrying connection (attempt 2/3)\n[2024-03-14 15:32:20] ERROR: Max retries exceeded",
"mimeType": "text/plain"
}
}
},
{
"role": "user",
"content": {
"type": "resource",
"resource": {
"uri": "file:///path/to/code.py",
"text": "def connect_to_service(timeout=30):\n retries = 3\n for attempt in range(retries):\n try:\n return establish_connection(timeout)\n except TimeoutError:\n if attempt == retries - 1:\n raise\n time.sleep(5)\n\ndef establish_connection(timeout):\n # Connection implementation\n pass",
"mimeType": "text/x-python"
}
}
}
]
}
```
### Multi-step workflows
```typescript
const debugWorkflow = {
name: "debug-error",
async getMessages(error: string) {
return [
{
role: "user",
content: {
type: "text",
text: `Here's an error I'm seeing: ${error}`
}
},
{
role: "assistant",
content: {
type: "text",
text: "I'll help analyze this error. What have you tried so far?"
}
},
{
role: "user",
content: {
type: "text",
text: "I've tried restarting the service, but the error persists."
}
}
];
}
};
```
## Example implementation
Here's a complete example of implementing prompts in an MCP server:
<Tabs>
<Tab title="TypeScript">
```typescript
import { Server } from "@modelcontextprotocol/sdk/server";
import {
ListPromptsRequestSchema,
GetPromptRequestSchema
} from "@modelcontextprotocol/sdk/types";
const PROMPTS = {
"git-commit": {
name: "git-commit",
description: "Generate a Git commit message",
arguments: [
{
name: "changes",
description: "Git diff or description of changes",
required: true
}
]
},
"explain-code": {
name: "explain-code",
description: "Explain how code works",
arguments: [
{
name: "code",
description: "Code to explain",
required: true
},
{
name: "language",
description: "Programming language",
required: false
}
]
}
};
const server = new Server({
name: "example-prompts-server",
version: "1.0.0"
}, {
capabilities: {
prompts: {}
}
});
// List available prompts
server.setRequestHandler(ListPromptsRequestSchema, async () => {
return {
prompts: Object.values(PROMPTS)
};
});
// Get specific prompt
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
const prompt = PROMPTS[request.params.name];
if (!prompt) {
throw new Error(`Prompt not found: ${request.params.name}`);
}
if (request.params.name === "git-commit") {
return {
messages: [
{
role: "user",
content: {
type: "text",
text: `Generate a concise but descriptive commit message for these changes:\n\n${request.params.arguments?.changes}`
}
}
]
};
}
if (request.params.name === "explain-code") {
const language = request.params.arguments?.language || "Unknown";
return {
messages: [
{
role: "user",
content: {
type: "text",
text: `Explain how this ${language} code works:\n\n${request.params.arguments?.code}`
}
}
]
};
}
throw new Error("Prompt implementation not found");
});
```
</Tab>
<Tab title="Python">
```python
from mcp.server import Server
import mcp.types as types
# Define available prompts
PROMPTS = {
"git-commit": types.Prompt(
name="git-commit",
description="Generate a Git commit message",
arguments=[
types.PromptArgument(
name="changes",
description="Git diff or description of changes",
required=True
)
],
),
"explain-code": types.Prompt(
name="explain-code",
description="Explain how code works",
arguments=[
types.PromptArgument(
name="code",
description="Code to explain",
required=True
),
types.PromptArgument(
name="language",
description="Programming language",
required=False
)
],
)
}
# Initialize server
app = Server("example-prompts-server")
@app.list_prompts()
async def list_prompts() -> list[types.Prompt]:
return list(PROMPTS.values())
@app.get_prompt()
async def get_prompt(
name: str, arguments: dict[str, str] | None = None
) -> types.GetPromptResult:
if name not in PROMPTS:
raise ValueError(f"Prompt not found: {name}")
if name == "git-commit":
changes = arguments.get("changes") if arguments else ""
return types.GetPromptResult(
messages=[
types.PromptMessage(
role="user",
content=types.TextContent(
type="text",
text=f"Generate a concise but descriptive commit message "
f"for these changes:\n\n{changes}"
)
)
]
)
if name == "explain-code":
code = arguments.get("code") if arguments else ""
language = arguments.get("language", "Unknown") if arguments else "Unknown"
return types.GetPromptResult(
messages=[
types.PromptMessage(
role="user",
content=types.TextContent(
type="text",
text=f"Explain how this {language} code works:\n\n{code}"
)
)
]
)
raise ValueError("Prompt implementation not found")
```
</Tab>
</Tabs>
## Best practices
When implementing prompts:
1. Use clear, descriptive prompt names
2. Provide detailed descriptions for prompts and arguments
3. Validate all required arguments
4. Handle missing arguments gracefully
5. Consider versioning for prompt templates
6. Cache dynamic content when appropriate
7. Implement error handling
8. Document expected argument formats
9. Consider prompt composability
10. Test prompts with various inputs
## UI integration
Prompts can be surfaced in client UIs as:
* Slash commands
* Quick actions
* Context menu items
* Command palette entries
* Guided workflows
* Interactive forms
## Updates and changes
Servers can notify clients about prompt changes:
1. Server capability: `prompts.listChanged`
2. Notification: `notifications/prompts/list_changed`
3. Client re-fetches prompt list
## Security considerations
When implementing prompts:
* Validate all arguments
* Sanitize user input
* Consider rate limiting
* Implement access controls
* Audit prompt usage
* Handle sensitive data appropriately
* Validate generated content
* Implement timeouts
* Consider prompt injection risks
* Document security requirements
# Resources
Source: https://modelcontextprotocol.io/docs/concepts/resources
Expose data and content from your servers to LLMs
Resources are a core primitive in the Model Context Protocol (MCP) that allow servers to expose data and content that can be read by clients and used as context for LLM interactions.
<Note>
Resources are designed to be **application-controlled**, meaning that the client application can decide how and when they should be used.
Different MCP clients may handle resources differently. For example:
* Claude Desktop currently requires users to explicitly select resources before they can be used
* Other clients might automatically select resources based on heuristics
* Some implementations may even allow the AI model itself to determine which resources to use
Server authors should be prepared to handle any of these interaction patterns when implementing resource support. In order to expose data to models automatically, server authors should use a **model-controlled** primitive such as [Tools](./tools).
</Note>
## Overview
Resources represent any kind of data that an MCP server wants to make available to clients. This can include:
* File contents
* Database records
* API responses
* Live system data
* Screenshots and images
* Log files
* And more
Each resource is identified by a unique URI and can contain either text or binary data.
## Resource URIs
Resources are identified using URIs that follow this format:
```
[protocol]://[host]/[path]
```
For example:
* `file:///home/user/documents/report.pdf`
* `postgres://database/customers/schema`
* `screen://localhost/display1`
The protocol and path structure is defined by the MCP server implementation. Servers can define their own custom URI schemes.
## Resource types
Resources can contain two types of content:
### Text resources
Text resources contain UTF-8 encoded text data. These are suitable for:
* Source code
* Configuration files
* Log files
* JSON/XML data
* Plain text
### Binary resources
Binary resources contain raw binary data encoded in base64. These are suitable for:
* Images
* PDFs
* Audio files
* Video files
* Other non-text formats
## Resource discovery
Clients can discover available resources through two main methods:
### Direct resources
Servers expose a list of concrete resources via the `resources/list` endpoint. Each resource includes:
```typescript
{
uri: string; // Unique identifier for the resource
name: string; // Human-readable name
description?: string; // Optional description
mimeType?: string; // Optional MIME type
}
```
### Resource templates
For dynamic resources, servers can expose [URI templates](https://datatracker.ietf.org/doc/html/rfc6570) that clients can use to construct valid resource URIs:
```typescript
{
uriTemplate: string; // URI template following RFC 6570
name: string; // Human-readable name for this type
description?: string; // Optional description
mimeType?: string; // Optional MIME type for all matching resources
}
```
## Reading resources
To read a resource, clients make a `resources/read` request with the resource URI.
The server responds with a list of resource contents:
```typescript
{
contents: [
{
uri: string; // The URI of the resource
mimeType?: string; // Optional MIME type
// One of:
text?: string; // For text resources
blob?: string; // For binary resources (base64 encoded)
}
]
}
```
<Tip>
Servers may return multiple resources in response to one `resources/read` request. This could be used, for example, to return a list of files inside a directory when the directory is read.
</Tip>
## Resource updates
MCP supports real-time updates for resources through two mechanisms:
### List changes
Servers can notify clients when their list of available resources changes via the `notifications/resources/list_changed` notification.
### Content changes
Clients can subscribe to updates for specific resources:
1. Client sends `resources/subscribe` with resource URI
2. Server sends `notifications/resources/updated` when the resource changes
3. Client can fetch latest content with `resources/read`
4. Client can unsubscribe with `resources/unsubscribe`
## Example implementation
Here's a simple example of implementing resource support in an MCP server:
<Tabs>
<Tab title="TypeScript">
```typescript
const server = new Server({
name: "example-server",
version: "1.0.0"
}, {
capabilities: {
resources: {}
}
});
// List available resources
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: "file:///logs/app.log",
name: "Application Logs",
mimeType: "text/plain"
}
]
};
});
// Read resource contents
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
const uri = request.params.uri;
if (uri === "file:///logs/app.log") {
const logContents = await readLogFile();
return {
contents: [
{
uri,
mimeType: "text/plain",
text: logContents
}
]
};
}
throw new Error("Resource not found");
});
```
</Tab>
<Tab title="Python">
```python
app = Server("example-server")
@app.list_resources()
async def list_resources() -> list[types.Resource]:
return [
types.Resource(
uri="file:///logs/app.log",
name="Application Logs",
mimeType="text/plain"
)
]
@app.read_resource()
async def read_resource(uri: AnyUrl) -> str:
if str(uri) == "file:///logs/app.log":
log_contents = await read_log_file()
return log_contents
raise ValueError("Resource not found")
# Start server
async with stdio_server() as streams:
await app.run(
streams[0],
streams[1],
app.create_initialization_options()
)
```
</Tab>
</Tabs>
## Best practices
When implementing resource support:
1. Use clear, descriptive resource names and URIs
2. Include helpful descriptions to guide LLM understanding
3. Set appropriate MIME types when known
4. Implement resource templates for dynamic content
5. Use subscriptions for frequently changing resources
6. Handle errors gracefully with clear error messages
7. Consider pagination for large resource lists
8. Cache resource contents when appropriate
9. Validate URIs before processing
10. Document your custom URI schemes
## Security considerations
When exposing resources:
* Validate all resource URIs
* Implement appropriate access controls
* Sanitize file paths to prevent directory traversal
* Be cautious with binary data handling
* Consider rate limiting for resource reads
* Audit resource access
* Encrypt sensitive data in transit
* Validate MIME types
* Implement timeouts for long-running reads
* Handle resource cleanup appropriately
# Roots
Source: https://modelcontextprotocol.io/docs/concepts/roots
Understanding roots in MCP
Roots are a concept in MCP that define the boundaries where servers can operate. They provide a way for clients to inform servers about relevant resources and their locations.
## What are Roots?
A root is a URI that a client suggests a server should focus on. When a client connects to a server, it declares which roots the server should work with. While primarily used for filesystem paths, roots can be any valid URI including HTTP URLs.
For example, roots could be:
```
file:///home/user/projects/myapp
https://api.example.com/v1
```
## Why Use Roots?
Roots serve several important purposes:
1. **Guidance**: They inform servers about relevant resources and locations
2. **Clarity**: Roots make it clear which resources are part of your workspace
3. **Organization**: Multiple roots let you work with different resources simultaneously
## How Roots Work
When a client supports roots, it:
1. Declares the `roots` capability during connection
2. Provides a list of suggested roots to the server
3. Notifies the server when roots change (if supported)
While roots are informational and not strictly enforcing, servers should:
1. Respect the provided roots
2. Use root URIs to locate and access resources
3. Prioritize operations within root boundaries
## Common Use Cases
Roots are commonly used to define:
* Project directories
* Repository locations
* API endpoints
* Configuration locations
* Resource boundaries
## Best Practices
When working with roots:
1. Only suggest necessary resources
2. Use clear, descriptive names for roots
3. Monitor root accessibility
4. Handle root changes gracefully
## Example
Here's how a typical MCP client might expose roots:
```json
{
"roots": [
{
"uri": "file:///home/user/projects/frontend",
"name": "Frontend Repository"
},
{
"uri": "https://api.example.com/v1",
"name": "API Endpoint"
}
]
}
```
This configuration suggests the server focus on both a local repository and an API endpoint while keeping them logically separated.
# Sampling
Source: https://modelcontextprotocol.io/docs/concepts/sampling
Let your servers request completions from LLMs
Sampling is a powerful MCP feature that allows servers to request LLM completions through the client, enabling sophisticated agentic behaviors while maintaining security and privacy.
<Info>
This feature of MCP is not yet supported in the Claude Desktop client.
</Info>
## How sampling works
The sampling flow follows these steps:
1. Server sends a `sampling/createMessage` request to the client
2. Client reviews the request and can modify it
3. Client samples from an LLM
4. Client reviews the completion
5. Client returns the result to the server
This human-in-the-loop design ensures users maintain control over what the LLM sees and generates.
## Message format
Sampling requests use a standardized message format:
```typescript
{
messages: [
{
role: "user" | "assistant",
content: {
type: "text" | "image",
// For text:
text?: string,
// For images:
data?: string, // base64 encoded
mimeType?: string
}
}
],
modelPreferences?: {
hints?: [{
name?: string // Suggested model name/family
}],
costPriority?: number, // 0-1, importance of minimizing cost
speedPriority?: number, // 0-1, importance of low latency
intelligencePriority?: number // 0-1, importance of capabilities
},
systemPrompt?: string,
includeContext?: "none" | "thisServer" | "allServers",
temperature?: number,
maxTokens: number,
stopSequences?: string[],
metadata?: Record<string, unknown>
}
```
## Request parameters
### Messages
The `messages` array contains the conversation history to send to the LLM. Each message has:
* `role`: Either "user" or "assistant"
* `content`: The message content, which can be:
* Text content with a `text` field
* Image content with `data` (base64) and `mimeType` fields
### Model preferences
The `modelPreferences` object allows servers to specify their model selection preferences:
* `hints`: Array of model name suggestions that clients can use to select an appropriate model:
* `name`: String that can match full or partial model names (e.g. "claude-3", "sonnet")
* Clients may map hints to equivalent models from different providers
* Multiple hints are evaluated in preference order
* Priority values (0-1 normalized):
* `costPriority`: Importance of minimizing costs
* `speedPriority`: Importance of low latency response
* `intelligencePriority`: Importance of advanced model capabilities
Clients make the final model selection based on these preferences and their available models.
### System prompt
An optional `systemPrompt` field allows servers to request a specific system prompt. The client may modify or ignore this.
### Context inclusion
The `includeContext` parameter specifies what MCP context to include:
* `"none"`: No additional context
* `"thisServer"`: Include context from the requesting server
* `"allServers"`: Include context from all connected MCP servers
The client controls what context is actually included.
### Sampling parameters
Fine-tune the LLM sampling with:
* `temperature`: Controls randomness (0.0 to 1.0)
* `maxTokens`: Maximum tokens to generate
* `stopSequences`: Array of sequences that stop generation
* `metadata`: Additional provider-specific parameters
## Response format
The client returns a completion result:
```typescript
{
model: string, // Name of the model used
stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string,
role: "user" | "assistant",
content: {
type: "text" | "image",
text?: string,
data?: string,
mimeType?: string
}
}
```
## Example request
Here's an example of requesting sampling from a client:
```json
{
"method": "sampling/createMessage",
"params": {
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "What files are in the current directory?"
}
}
],
"systemPrompt": "You are a helpful file system assistant.",
"includeContext": "thisServer",
"maxTokens": 100
}
}
```
## Best practices
When implementing sampling:
1. Always provide clear, well-structured prompts
2. Handle both text and image content appropriately
3. Set reasonable token limits
4. Include relevant context through `includeContext`
5. Validate responses before using them
6. Handle errors gracefully
7. Consider rate limiting sampling requests
8. Document expected sampling behavior
9. Test with various model parameters
10. Monitor sampling costs
## Human in the loop controls
Sampling is designed with human oversight in mind:
### For prompts
* Clients should show users the proposed prompt
* Users should be able to modify or reject prompts
* System prompts can be filtered or modified
* Context inclusion is controlled by the client
### For completions
* Clients should show users the completion
* Users should be able to modify or reject completions
* Clients can filter or modify completions
* Users control which model is used
## Security considerations
When implementing sampling:
* Validate all message content
* Sanitize sensitive information
* Implement appropriate rate limits
* Monitor sampling usage
* Encrypt data in transit
* Handle user data privacy
* Audit sampling requests
* Control cost exposure
* Implement timeouts
* Handle model errors gracefully
## Common patterns
### Agentic workflows
Sampling enables agentic patterns like:
* Reading and analyzing resources
* Making decisions based on context
* Generating structured data
* Handling multi-step tasks
* Providing interactive assistance
### Context management
Best practices for context:
* Request minimal necessary context
* Structure context clearly
* Handle context size limits
* Update context as needed
* Clean up stale context
### Error handling
Robust error handling should:
* Catch sampling failures
* Handle timeout errors
* Manage rate limits
* Validate responses
* Provide fallback behaviors
* Log errors appropriately
## Limitations
Be aware of these limitations:
* Sampling depends on client capabilities
* Users control sampling behavior
* Context size has limits
* Rate limits may apply
* Costs should be considered
* Model availability varies
* Response times vary
* Not all content types supported
# Tools
Source: https://modelcontextprotocol.io/docs/concepts/tools
Enable LLMs to perform actions through your server
Tools are a powerful primitive in the Model Context Protocol (MCP) that enable servers to expose executable functionality to clients. Through tools, LLMs can interact with external systems, perform computations, and take actions in the real world.
<Note>
Tools are designed to be **model-controlled**, meaning that tools are exposed from servers to clients with the intention of the AI model being able to automatically invoke them (with a human in the loop to grant approval).
</Note>
## Overview
Tools in MCP allow servers to expose executable functions that can be invoked by clients and used by LLMs to perform actions. Key aspects of tools include:
* **Discovery**: Clients can list available tools through the `tools/list` endpoint
* **Invocation**: Tools are called using the `tools/call` endpoint, where servers perform the requested operation and return results
* **Flexibility**: Tools can range from simple calculations to complex API interactions
Like [resources](/docs/concepts/resources), tools are identified by unique names and can include descriptions to guide their usage. However, unlike resources, tools represent dynamic operations that can modify state or interact with external systems.
## Tool definition structure
Each tool is defined with the following structure:
```typescript
{
name: string; // Unique identifier for the tool
description?: string; // Human-readable description
inputSchema: { // JSON Schema for the tool's parameters
type: "object",
properties: { ... } // Tool-specific parameters
}
}
```
## Implementing tools
Here's an example of implementing a basic tool in an MCP server:
<Tabs>
<Tab title="TypeScript">
```typescript
const server = new Server({
name: "example-server",
version: "1.0.0"
}, {
capabilities: {
tools: {}
}
});
// Define available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [{
name: "calculate_sum",
description: "Add two numbers together",
inputSchema: {
type: "object",
properties: {
a: { type: "number" },
b: { type: "number" }
},
required: ["a", "b"]
}
}]
};
});
// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === "calculate_sum") {
const { a, b } = request.params.arguments;
return {
content: [
{
type: "text",
text: String(a + b)
}
]
};
}
throw new Error("Tool not found");
});
```
</Tab>
<Tab title="Python">
```python
app = Server("example-server")
@app.list_tools()
async def list_tools() -> list[types.Tool]:
return [
types.Tool(
name="calculate_sum",
description="Add two numbers together",
inputSchema={
"type": "object",
"properties": {
"a": {"type": "number"},
"b": {"type": "number"}
},
"required": ["a", "b"]
}
)
]
@app.call_tool()
async def call_tool(
name: str,
arguments: dict
) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
if name == "calculate_sum":
a = arguments["a"]
b = arguments["b"]
result = a + b
return [types.TextContent(type="text", text=str(result))]
raise ValueError(f"Tool not found: {name}")
```
</Tab>
</Tabs>
## Example tool patterns
Here are some examples of types of tools that a server could provide:
### System operations
Tools that interact with the local system:
```typescript
{
name: "execute_command",
description: "Run a shell command",
inputSchema: {
type: "object",
properties: {
command: { type: "string" },
args: { type: "array", items: { type: "string" } }
}
}
}
```
### API integrations
Tools that wrap external APIs:
```typescript
{
name: "github_create_issue",
description: "Create a GitHub issue",
inputSchema: {
type: "object",
properties: {
title: { type: "string" },
body: { type: "string" },
labels: { type: "array", items: { type: "string" } }
}
}
}
```
### Data processing
Tools that transform or analyze data:
```typescript
{
name: "analyze_csv",
description: "Analyze a CSV file",
inputSchema: {
type: "object",
properties: {
filepath: { type: "string" },
operations: {
type: "array",
items: {
enum: ["sum", "average", "count"]
}
}
}
}
}
```
## Best practices
When implementing tools:
1. Provide clear, descriptive names and descriptions
2. Use detailed JSON Schema definitions for parameters
3. Include examples in tool descriptions to demonstrate how the model should use them
4. Implement proper error handling and validation
5. Use progress reporting for long operations
6. Keep tool operations focused and atomic
7. Document expected return value structures
8. Implement proper timeouts
9. Consider rate limiting for resource-intensive operations
10. Log tool usage for debugging and monitoring
## Security considerations
When exposing tools:
### Input validation
* Validate all parameters against the schema
* Sanitize file paths and system commands
* Validate URLs and external identifiers
* Check parameter sizes and ranges
* Prevent command injection
### Access control
* Implement authentication where needed
* Use appropriate authorization checks
* Audit tool usage
* Rate limit requests
* Monitor for abuse
### Error handling
* Don't expose internal errors to clients
* Log security-relevant errors
* Handle timeouts appropriately
* Clean up resources after errors
* Validate return values
## Tool discovery and updates
MCP supports dynamic tool discovery:
1. Clients can list available tools at any time
2. Servers can notify clients when tools change using `notifications/tools/list_changed`
3. Tools can be added or removed during runtime
4. Tool definitions can be updated (though this should be done carefully)
## Error handling
Tool errors should be reported within the result object, not as MCP protocol-level errors. This allows the LLM to see and potentially handle the error. When a tool encounters an error:
1. Set `isError` to `true` in the result
2. Include error details in the `content` array
Here's an example of proper error handling for tools:
<Tabs>
<Tab title="TypeScript">
```typescript
try {
// Tool operation
const result = performOperation();
return {
content: [
{
type: "text",
text: `Operation successful: ${result}`
}
]
};
} catch (error) {
return {
isError: true,
content: [
{
type: "text",
text: `Error: ${error.message}`
}
]
};
}
```
</Tab>
<Tab title="Python">
```python
try:
# Tool operation
result = perform_operation()
return types.CallToolResult(
content=[
types.TextContent(
type="text",
text=f"Operation successful: {result}"
)
]
)
except Exception as error:
return types.CallToolResult(
isError=True,
content=[
types.TextContent(
type="text",
text=f"Error: {str(error)}"
)
]
)
```
</Tab>
</Tabs>
This approach allows the LLM to see that an error occurred and potentially take corrective action or request human intervention.
## Testing tools
A comprehensive testing strategy for MCP tools should cover:
* **Functional testing**: Verify tools execute correctly with valid inputs and handle invalid inputs appropriately
* **Integration testing**: Test tool interaction with external systems using both real and mocked dependencies
* **Security testing**: Validate authentication, authorization, input sanitization, and rate limiting
* **Performance testing**: Check behavior under load, timeout handling, and resource cleanup
* **Error handling**: Ensure tools properly report errors through the MCP protocol and clean up resources
# Transports
Source: https://modelcontextprotocol.io/docs/concepts/transports
Learn about MCP's communication mechanisms
Transports in the Model Context Protocol (MCP) provide the foundation for communication between clients and servers. A transport handles the underlying mechanics of how messages are sent and received.
## Message Format
MCP uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 as its wire format. The transport layer is responsible for converting MCP protocol messages into JSON-RPC format for transmission and converting received JSON-RPC messages back into MCP protocol messages.
There are three types of JSON-RPC messages used:
### Requests
```typescript
{
jsonrpc: "2.0",
id: number | string,
method: string,
params?: object
}
```
### Responses
```typescript
{
jsonrpc: "2.0",
id: number | string,
result?: object,
error?: {
code: number,
message: string,
data?: unknown
}
}
```
### Notifications
```typescript
{
jsonrpc: "2.0",
method: string,
params?: object
}
```
## Built-in Transport Types
MCP includes two standard transport implementations:
### Standard Input/Output (stdio)
The stdio transport enables communication through standard input and output streams. This is particularly useful for local integrations and command-line tools.
Use stdio when:
* Building command-line tools
* Implementing local integrations
* Needing simple process communication
* Working with shell scripts
<Tabs>
<Tab title="TypeScript (Server)">
```typescript
const server = new Server({
name: "example-server",
version: "1.0.0"
}, {
capabilities: {}
});
const transport = new StdioServerTransport();
await server.connect(transport);
```
</Tab>
<Tab title="TypeScript (Client)">
```typescript
const client = new Client({
name: "example-client",
version: "1.0.0"
}, {
capabilities: {}
});
const transport = new StdioClientTransport({
command: "./server",
args: ["--option", "value"]
});
await client.connect(transport);
```
</Tab>
<Tab title="Python (Server)">
```python
app = Server("example-server")
async with stdio_server() as streams:
await app.run(
streams[0],
streams[1],
app.create_initialization_options()
)
```
</Tab>
<Tab title="Python (Client)">
```python
params = StdioServerParameters(
command="./server",
args=["--option", "value"]
)
async with stdio_client(params) as streams:
async with ClientSession(streams[0], streams[1]) as session:
await session.initialize()
```
</Tab>
</Tabs>
### Server-Sent Events (SSE)
SSE transport enables server-to-client streaming with HTTP POST requests for client-to-server communication.
Use SSE when:
* Only server-to-client streaming is needed
* Working with restricted networks
* Implementing simple updates
<Tabs>
<Tab title="TypeScript (Server)">
```typescript
import express from "express";
const app = express();
const server = new Server({
name: "example-server",
version: "1.0.0"
}, {
capabilities: {}
});
let transport: SSEServerTransport | null = null;
app.get("/sse", (req, res) => {
transport = new SSEServerTransport("/messages", res);
server.connect(transport);
});
app.post("/messages", (req, res) => {
if (transport) {
transport.handlePostMessage(req, res);
}
});
app.listen(3000);
```
</Tab>
<Tab title="TypeScript (Client)">
```typescript
const client = new Client({
name: "example-client",
version: "1.0.0"
}, {
capabilities: {}
});
const transport = new SSEClientTransport(
new URL("http://localhost:3000/sse")
);
await client.connect(transport);
```
</Tab>
<Tab title="Python (Server)">
```python
from mcp.server.sse import SseServerTransport
from starlette.applications import Starlette
from starlette.routing import Route
app = Server("example-server")
sse = SseServerTransport("/messages")
async def handle_sse(scope, receive, send):
async with sse.connect_sse(scope, receive, send) as streams:
await app.run(streams[0], streams[1], app.create_initialization_options())
async def handle_messages(scope, receive, send):
await sse.handle_post_message(scope, receive, send)
starlette_app = Starlette(
routes=[
Route("/sse", endpoint=handle_sse),
Route("/messages", endpoint=handle_messages, methods=["POST"]),
]
)
```
</Tab>
<Tab title="Python (Client)">
```python
async with sse_client("http://localhost:8000/sse") as streams:
async with ClientSession(streams[0], streams[1]) as session:
await session.initialize()
```
</Tab>
</Tabs>
## Custom Transports
MCP makes it easy to implement custom transports for specific needs. Any transport implementation just needs to conform to the Transport interface:
You can implement custom transports for:
* Custom network protocols
* Specialized communication channels
* Integration with existing systems
* Performance optimization
<Tabs>
<Tab title="TypeScript">
```typescript
interface Transport {
// Start processing messages
start(): Promise<void>;
// Send a JSON-RPC message
send(message: JSONRPCMessage): Promise<void>;
// Close the connection
close(): Promise<void>;
// Callbacks
onclose?: () => void;
onerror?: (error: Error) => void;
onmessage?: (message: JSONRPCMessage) => void;
}
```
</Tab>
<Tab title="Python">
Note that while MCP Servers are often implemented with asyncio, we recommend
implementing low-level interfaces like transports with `anyio` for wider compatibility.
```python
@contextmanager
async def create_transport(
read_stream: MemoryObjectReceiveStream[JSONRPCMessage | Exception],
write_stream: MemoryObjectSendStream[JSONRPCMessage]
):
"""
Transport interface for MCP.
Args:
read_stream: Stream to read incoming messages from
write_stream: Stream to write outgoing messages to
"""
async with anyio.create_task_group() as tg:
try:
# Start processing messages
tg.start_soon(lambda: process_messages(read_stream))
# Send messages
async with write_stream:
yield write_stream
except Exception as exc:
# Handle errors
raise exc
finally:
# Clean up
tg.cancel_scope.cancel()
await write_stream.aclose()
await read_stream.aclose()
```
</Tab>
</Tabs>
## Error Handling
Transport implementations should handle various error scenarios:
1. Connection errors
2. Message parsing errors
3. Protocol errors
4. Network timeouts
5. Resource cleanup
Example error handling:
<Tabs>
<Tab title="TypeScript">
```typescript
class ExampleTransport implements Transport {
async start() {
try {
// Connection logic
} catch (error) {
this.onerror?.(new Error(`Failed to connect: ${error}`));
throw error;
}
}
async send(message: JSONRPCMessage) {
try {
// Sending logic
} catch (error) {
this.onerror?.(new Error(`Failed to send message: ${error}`));
throw error;
}
}
}
```
</Tab>
<Tab title="Python">
Note that while MCP Servers are often implemented with asyncio, we recommend
implementing low-level interfaces like transports with `anyio` for wider compatibility.
```python
@contextmanager
async def example_transport(scope: Scope, receive: Receive, send: Send):
try:
# Create streams for bidirectional communication
read_stream_writer, read_stream = anyio.create_memory_object_stream(0)
write_stream, write_stream_reader = anyio.create_memory_object_stream(0)
async def message_handler():
try:
async with read_stream_writer:
# Message handling logic
pass
except Exception as exc:
logger.error(f"Failed to handle message: {exc}")
raise exc
async with anyio.create_task_group() as tg:
tg.start_soon(message_handler)
try:
# Yield streams for communication
yield read_stream, write_stream
except Exception as exc:
logger.error(f"Transport error: {exc}")
raise exc
finally:
tg.cancel_scope.cancel()
await write_stream.aclose()
await read_stream.aclose()
except Exception as exc:
logger.error(f"Failed to initialize transport: {exc}")
raise exc
```
</Tab>
</Tabs>
## Best Practices
When implementing or using MCP transport:
1. Handle connection lifecycle properly
2. Implement proper error handling
3. Clean up resources on connection close
4. Use appropriate timeouts
5. Validate messages before sending
6. Log transport events for debugging
7. Implement reconnection logic when appropriate
8. Handle backpressure in message queues
9. Monitor connection health
10. Implement proper security measures
## Security Considerations
When implementing transport:
### Authentication and Authorization
* Implement proper authentication mechanisms
* Validate client credentials
* Use secure token handling
* Implement authorization checks
### Data Security
* Use TLS for network transport
* Encrypt sensitive data
* Validate message integrity
* Implement message size limits
* Sanitize input data
### Network Security
* Implement rate limiting
* Use appropriate timeouts
* Handle denial of service scenarios
* Monitor for unusual patterns
* Implement proper firewall rules
## Debugging Transport
Tips for debugging transport issues:
1. Enable debug logging
2. Monitor message flow
3. Check connection states
4. Validate message formats
5. Test error scenarios
6. Use network analysis tools
7. Implement health checks
8. Monitor resource usage
9. Test edge cases
10. Use proper error tracking
# Debugging
Source: https://modelcontextprotocol.io/docs/tools/debugging
A comprehensive guide to debugging Model Context Protocol (MCP) integrations
Effective debugging is essential when developing MCP servers or integrating them with applications. This guide covers the debugging tools and approaches available in the MCP ecosystem.
<Info>
This guide is for macOS. Guides for other platforms are coming soon.
</Info>
## Debugging tools overview
MCP provides several tools for debugging at different levels:
1. **MCP Inspector**
* Interactive debugging interface
* Direct server testing
* See the [Inspector guide](/docs/tools/inspector) for details
2. **Claude Desktop Developer Tools**
* Integration testing
* Log collection
* Chrome DevTools integration
3. **Server Logging**
* Custom logging implementations
* Error tracking
* Performance monitoring
## Debugging in Claude Desktop
### Checking server status
The Claude.app interface provides basic server status information:
1. Click the <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-plug-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon to view:
* Connected servers
* Available prompts and resources
2. Click the <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon to view:
* Tools made available to the model
### Viewing logs
Review detailed MCP logs from Claude Desktop:
```bash
# Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
```
The logs capture:
* Server connection events
* Configuration issues
* Runtime errors
* Message exchanges
### Using Chrome DevTools
Access Chrome's developer tools inside Claude Desktop to investigate client-side errors:
1. Create a `developer_settings.json` file with `allowDevTools` set to true:
```bash
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
```
2. Open DevTools: `Command-Option-Shift-i`
Note: You'll see two DevTools windows:
* Main content window
* App title bar window
Use the Console panel to inspect client-side errors.
Use the Network panel to inspect:
* Message payloads
* Connection timing
## Common issues
### Working directory
When using MCP servers with Claude Desktop:
* The working directory for servers launched via `claude_desktop_config.json` may be undefined (like `/` on macOS) since Claude Desktop could be started from anywhere
* Always use absolute paths in your configuration and `.env` files to ensure reliable operation
* For testing servers directly via command line, the working directory will be where you run the command
For example in `claude_desktop_config.json`, use:
```json
{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}
```
Instead of relative paths like `./data`
### Environment variables
MCP servers inherit only a subset of environment variables automatically, like `USER`, `HOME`, and `PATH`.
To override the default variables or provide your own, you can specify an `env` key in `claude_desktop_config.json`:
```json
{
"myserver": {
"command": "mcp-server-myapp",
"env": {
"MYAPP_API_KEY": "some_key",
}
}
}
```
### Server initialization
Common initialization problems:
1. **Path Issues**
* Incorrect server executable path
* Missing required files
* Permission problems
* Try using an absolute path for `command`
2. **Configuration Errors**
* Invalid JSON syntax
* Missing required fields
* Type mismatches
3. **Environment Problems**
* Missing environment variables
* Incorrect variable values
* Permission restrictions
### Connection problems
When servers fail to connect:
1. Check Claude Desktop logs
2. Verify server process is running
3. Test standalone with [Inspector](/docs/tools/inspector)
4. Verify protocol compatibility
## Implementing logging
### Server-side logging
When building a server that uses the local stdio [transport](/docs/concepts/transports), all messages logged to stderr (standard error) will be captured by the host application (e.g., Claude Desktop) automatically.
<Warning>
Local MCP servers should not log messages to stdout (standard out), as this will interfere with protocol operation.
</Warning>
For all [transports](/docs/concepts/transports), you can also provide logging to the client by sending a log message notification:
<Tabs>
<Tab title="Python">
```python
server.request_context.session.send_log_message(
level="info",
data="Server started successfully",
)
```
</Tab>
<Tab title="TypeScript">
```typescript
server.sendLoggingMessage({
level: "info",
data: "Server started successfully",
});
```
</Tab>
</Tabs>
Important events to log:
* Initialization steps
* Resource access
* Tool execution
* Error conditions
* Performance metrics
### Client-side logging
In client applications:
1. Enable debug logging
2. Monitor network traffic
3. Track message exchanges
4. Record error states
## Debugging workflow
### Development cycle
1. Initial Development
* Use [Inspector](/docs/tools/inspector) for basic testing
* Implement core functionality
* Add logging points
2. Integration Testing
* Test in Claude Desktop
* Monitor logs
* Check error handling
### Testing changes
To test changes efficiently:
* **Configuration changes**: Restart Claude Desktop
* **Server code changes**: Use Command-R to reload
* **Quick iteration**: Use [Inspector](/docs/tools/inspector) during development
## Best practices
### Logging strategy
1. **Structured Logging**
* Use consistent formats
* Include context
* Add timestamps
* Track request IDs
2. **Error Handling**
* Log stack traces
* Include error context
* Track error patterns
* Monitor recovery
3. **Performance Tracking**
* Log operation timing
* Monitor resource usage
* Track message sizes
* Measure latency
### Security considerations
When debugging:
1. **Sensitive Data**
* Sanitize logs
* Protect credentials
* Mask personal information
2. **Access Control**
* Verify permissions
* Check authentication
* Monitor access patterns
## Getting help
When encountering issues:
1. **First Steps**
* Check server logs
* Test with [Inspector](/docs/tools/inspector)
* Review configuration
* Verify environment
2. **Support Channels**
* GitHub issues
* GitHub discussions
3. **Providing Information**
* Log excerpts
* Configuration files
* Steps to reproduce
* Environment details
## Next steps
<CardGroup cols={2}>
<Card title="MCP Inspector" icon="magnifying-glass" href="/docs/tools/inspector">
Learn to use the MCP Inspector
</Card>
</CardGroup>
# Inspector
Source: https://modelcontextprotocol.io/docs/tools/inspector
In-depth guide to using the MCP Inspector for testing and debugging Model Context Protocol servers
The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive developer tool for testing and debugging MCP servers. While the [Debugging Guide](/docs/tools/debugging) covers the Inspector as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector's features and capabilities.
## Getting started
### Installation and basic usage
The Inspector runs directly through `npx` without requiring installation:
```bash
npx @modelcontextprotocol/inspector <command>
```
```bash
npx @modelcontextprotocol/inspector <command> <arg1> <arg2>
```
#### Inspecting servers from NPM or PyPi
A common way to start server packages from [NPM](https://npmjs.com) or [PyPi](https://pypi.com).
<Tabs>
<Tab title="NPM package">
```bash
npx -y @modelcontextprotocol/inspector npx <package-name> <args>
# For example
npx -y @modelcontextprotocol/inspector npx server-postgres postgres://127.0.0.1/testdb
```
</Tab>
<Tab title="PyPi package">
```bash
npx @modelcontextprotocol/inspector uvx <package-name> <args>
# For example
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git
```
</Tab>
</Tabs>
#### Inspecting locally developed servers
To inspect servers locally developed or downloaded as a repository, the most common
way is:
<Tabs>
<Tab title="TypeScript">
```bash
npx @modelcontextprotocol/inspector node path/to/server/index.js args...
```
</Tab>
<Tab title="Python">
```bash
npx @modelcontextprotocol/inspector \
uv \
--directory path/to/server \
run \
package-name \
args...
```
</Tab>
</Tabs>
Please carefully read any attached README for the most accurate instructions.
## Feature overview
<Frame caption="The MCP Inspector interface">
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/mcp-inspector.png" />
</Frame>
The Inspector provides several features for interacting with your MCP server:
### Server connection pane
* Allows selecting the [transport](/docs/concepts/transports) for connecting to the server
* For local servers, supports customizing the command-line arguments and environment
### Resources tab
* Lists all available resources
* Shows resource metadata (MIME types, descriptions)
* Allows resource content inspection
* Supports subscription testing
### Prompts tab
* Displays available prompt templates
* Shows prompt arguments and descriptions
* Enables prompt testing with custom arguments
* Previews generated messages
### Tools tab
* Lists available tools
* Shows tool schemas and descriptions
* Enables tool testing with custom inputs
* Displays tool execution results
### Notifications pane
* Presents all logs recorded from the server
* Shows notifications received from the server
## Best practices
### Development workflow
1. Start Development
* Launch Inspector with your server
* Verify basic connectivity
* Check capability negotiation
2. Iterative testing
* Make server changes
* Rebuild the server
* Reconnect the Inspector
* Test affected features
* Monitor messages
3. Test edge cases
* Invalid inputs
* Missing prompt arguments
* Concurrent operations
* Verify error handling and error responses
## Next steps
<CardGroup cols={2}>
<Card title="Inspector Repository" icon="github" href="https://github.com/modelcontextprotocol/inspector">
Check out the MCP Inspector source code
</Card>
<Card title="Debugging Guide" icon="bug" href="/docs/tools/debugging">
Learn about broader debugging strategies
</Card>
</CardGroup>
# Example Servers
Source: https://modelcontextprotocol.io/examples
A list of example servers and implementations
This page showcases various Model Context Protocol (MCP) servers that demonstrate the protocol's capabilities and versatility. These servers enable Large Language Models (LLMs) to securely access tools and data sources.
## Reference implementations
These official reference servers demonstrate core MCP features and SDK usage:
### Data and file systems
* **[Filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)** - Secure file operations with configurable access controls
* **[PostgreSQL](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres)** - Read-only database access with schema inspection capabilities
* **[SQLite](https://github.com/modelcontextprotocol/servers/tree/main/src/sqlite)** - Database interaction and business intelligence features
* **[Google Drive](https://github.com/modelcontextprotocol/servers/tree/main/src/gdrive)** - File access and search capabilities for Google Drive
### Development tools
* **[Git](https://github.com/modelcontextprotocol/servers/tree/main/src/git)** - Tools to read, search, and manipulate Git repositories
* **[GitHub](https://github.com/modelcontextprotocol/servers/tree/main/src/github)** - Repository management, file operations, and GitHub API integration
* **[GitLab](https://github.com/modelcontextprotocol/servers/tree/main/src/gitlab)** - GitLab API integration enabling project management
* **[Sentry](https://github.com/modelcontextprotocol/servers/tree/main/src/sentry)** - Retrieving and analyzing issues from Sentry.io
### Web and browser automation
* **[Brave Search](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search)** - Web and local search using Brave's Search API
* **[Fetch](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch)** - Web content fetching and conversion optimized for LLM usage
* **[Puppeteer](https://github.com/modelcontextprotocol/servers/tree/main/src/puppeteer)** - Browser automation and web scraping capabilities
### Productivity and communication
* **[Slack](https://github.com/modelcontextprotocol/servers/tree/main/src/slack)** - Channel management and messaging capabilities
* **[Google Maps](https://github.com/modelcontextprotocol/servers/tree/main/src/google-maps)** - Location services, directions, and place details
* **[Memory](https://github.com/modelcontextprotocol/servers/tree/main/src/memory)** - Knowledge graph-based persistent memory system
### AI and specialized tools
* **[EverArt](https://github.com/modelcontextprotocol/servers/tree/main/src/everart)** - AI image generation using various models
* **[Sequential Thinking](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking)** - Dynamic problem-solving through thought sequences
* **[AWS KB Retrieval](https://github.com/modelcontextprotocol/servers/tree/main/src/aws-kb-retrieval-server)** - Retrieval from AWS Knowledge Base using Bedrock Agent Runtime
## Official integrations
These MCP servers are maintained by companies for their platforms:
* **[Axiom](https://github.com/axiomhq/mcp-server-axiom)** - Query and analyze logs, traces, and event data using natural language
* **[Browserbase](https://github.com/browserbase/mcp-server-browserbase)** - Automate browser interactions in the cloud
* **[Cloudflare](https://github.com/cloudflare/mcp-server-cloudflare)** - Deploy and manage resources on the Cloudflare developer platform
* **[E2B](https://github.com/e2b-dev/mcp-server)** - Execute code in secure cloud sandboxes
* **[Neon](https://github.com/neondatabase/mcp-server-neon)** - Interact with the Neon serverless Postgres platform
* **[Obsidian Markdown Notes](https://github.com/calclavia/mcp-obsidian)** - Read and search through Markdown notes in Obsidian vaults
* **[Qdrant](https://github.com/qdrant/mcp-server-qdrant/)** - Implement semantic memory using the Qdrant vector search engine
* **[Raygun](https://github.com/MindscapeHQ/mcp-server-raygun)** - Access crash reporting and monitoring data
* **[Search1API](https://github.com/fatwang2/search1api-mcp)** - Unified API for search, crawling, and sitemaps
* **[Stripe](https://github.com/stripe/agent-toolkit)** - Interact with the Stripe API
* **[Tinybird](https://github.com/tinybirdco/mcp-tinybird)** - Interface with the Tinybird serverless ClickHouse platform
* **[Weaviate](https://github.com/weaviate/mcp-server-weaviate)** - Enable Agentic RAG through your Weaviate collection(s)
## Community highlights
A growing ecosystem of community-developed servers extends MCP's capabilities:
* **[Docker](https://github.com/ckreiling/mcp-server-docker)** - Manage containers, images, volumes, and networks
* **[Kubernetes](https://github.com/Flux159/mcp-server-kubernetes)** - Manage pods, deployments, and services
* **[Linear](https://github.com/jerhadf/linear-mcp-server)** - Project management and issue tracking
* **[Snowflake](https://github.com/datawiz168/mcp-snowflake-service)** - Interact with Snowflake databases
* **[Spotify](https://github.com/varunneal/spotify-mcp)** - Control Spotify playback and manage playlists
* **[Todoist](https://github.com/abhiz123/todoist-mcp-server)** - Task management integration
> **Note:** Community servers are untested and should be used at your own risk. They are not affiliated with or endorsed by Anthropic.
For a complete list of community servers, visit the [MCP Servers Repository](https://github.com/modelcontextprotocol/servers).
## Getting started
### Using reference servers
TypeScript-based servers can be used directly with `npx`:
```bash
npx -y @modelcontextprotocol/server-memory
```
Python-based servers can be used with `uvx` (recommended) or `pip`:
```bash
# Using uvx
uvx mcp-server-git
# Using pip
pip install mcp-server-git
python -m mcp_server_git
```
### Configuring with Claude
To use an MCP server with Claude, add it to your configuration:
```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
}
}
}
}
```
## Additional resources
* [MCP Servers Repository](https://github.com/modelcontextprotocol/servers) - Complete collection of reference implementations and community servers
* [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) - Curated list of MCP servers
* [MCP CLI](https://github.com/wong2/mcp-cli) - Command-line inspector for testing MCP servers
* [MCP Get](https://mcp-get.com) - Tool for installing and managing MCP servers
* [Supergateway](https://github.com/supercorp-ai/supergateway) - Run MCP stdio servers over SSE
Visit our [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions) to engage with the MCP community.
# Introduction
Source: https://modelcontextprotocol.io/introduction
Get started with the Model Context Protocol (MCP)
<Note>Java SDK released! Check out [what else is new.](/development/updates)</Note>
MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.
## Why MCP?
MCP helps you build agents and complex workflows on top of LLMs. LLMs frequently need to integrate with data and tools, and MCP provides:
* A growing list of pre-built integrations that your LLM can directly plug into
* The flexibility to switch between LLM providers and vendors
* Best practices for securing your data within your infrastructure
### General architecture
At its core, MCP follows a client-server architecture where a host application can connect to multiple servers:
```mermaid
flowchart LR
subgraph "Your Computer"
Host["Host with MCP Client\n(Claude, IDEs, Tools)"]
S1["MCP Server A"]
S2["MCP Server B"]
S3["MCP Server C"]
Host <-->|"MCP Protocol"| S1
Host <-->|"MCP Protocol"| S2
Host <-->|"MCP Protocol"| S3
S1 <--> D1[("Local\nData Source A")]
S2 <--> D2[("Local\nData Source B")]
end
subgraph "Internet"
S3 <-->|"Web APIs"| D3[("Remote\nService C")]
end
```
* **MCP Hosts**: Programs like Claude Desktop, IDEs, or AI tools that want to access data through MCP
* **MCP Clients**: Protocol clients that maintain 1:1 connections with servers
* **MCP Servers**: Lightweight programs that each expose specific capabilities through the standardized Model Context Protocol
* **Local Data Sources**: Your computer's files, databases, and services that MCP servers can securely access
* **Remote Services**: External systems available over the internet (e.g., through APIs) that MCP servers can connect to
## Get started
Choose the path that best fits your needs:
#### Quick Starts
<CardGroup cols={2}>
<Card title="For Server Developers" icon="bolt" href="/quickstart/server">
Get started building your own server to use in Claude for Desktop and other clients
</Card>
<Card title="For Client Developers" icon="bolt" href="/quickstart/client">
Get started building your own client that can integrate with all MCP servers
</Card>
<Card title="For Claude Desktop Users" icon="bolt" href="/quickstart/user">
Get started using pre-built servers in Claude for Desktop
</Card>
</CardGroup>
#### Examples
<CardGroup cols={2}>
<Card title="Example Servers" icon="grid" href="/examples">
Check out our gallery of official MCP servers and implementations
</Card>
<Card title="Example Clients" icon="cubes" href="/clients">
View the list of clients that support MCP integrations
</Card>
</CardGroup>
## Tutorials
<CardGroup cols={2}>
<Card title="Building MCP with LLMs" icon="comments" href="/tutorials/building-mcp-with-llms">
Learn how to use LLMs like Claude to speed up your MCP development
</Card>
<Card title="Debugging Guide" icon="bug" href="/docs/tools/debugging">
Learn how to effectively debug MCP servers and integrations
</Card>
<Card title="MCP Inspector" icon="magnifying-glass" href="/docs/tools/inspector">
Test and inspect your MCP servers with our interactive debugging tool
</Card>
<Card title="MCP Workshop (Video, 2hr)" icon="person-chalkboard" href="https://www.youtube.com/watch?v=kQmXtrmQ5Zg">
<iframe src="https://www.youtube.com/embed/kQmXtrmQ5Zg" />
</Card>
</CardGroup>
## Explore MCP
Dive deeper into MCP's core concepts and capabilities:
<CardGroup cols={2}>
<Card title="Core architecture" icon="sitemap" href="/docs/concepts/architecture">
Understand how MCP connects clients, servers, and LLMs
</Card>
<Card title="Resources" icon="database" href="/docs/concepts/resources">
Expose data and content from your servers to LLMs
</Card>
<Card title="Prompts" icon="message" href="/docs/concepts/prompts">
Create reusable prompt templates and workflows
</Card>
<Card title="Tools" icon="wrench" href="/docs/concepts/tools">
Enable LLMs to perform actions through your server
</Card>
<Card title="Sampling" icon="robot" href="/docs/concepts/sampling">
Let your servers request completions from LLMs
</Card>
<Card title="Transports" icon="network-wired" href="/docs/concepts/transports">
Learn about MCP's communication mechanism
</Card>
</CardGroup>
## Contributing
Want to contribute? Check out our [Contributing Guide](/development/contributing) to learn how you can help improve MCP.
## Support and Feedback
Here's how to get help or provide feedback:
* For bug reports and feature requests related to the MCP specification, SDKs, or documentation (open source), please [create a GitHub issue](https://github.com/modelcontextprotocol)
* For discussions or Q\&A about the MCP specification, use the [specification discussions](https://github.com/modelcontextprotocol/specification/discussions)
* For discussions or Q\&A about other MCP open source components, use the [organization discussions](https://github.com/orgs/modelcontextprotocol/discussions)
* For bug reports, feature requests, and questions related to Claude.app and claude.ai's MCP integration, please email [mcp-support@anthropic.com](mailto:mcp-support@anthropic.com)
# For Client Developers
Source: https://modelcontextprotocol.io/quickstart/client
Get started building your own client that can integrate with all MCP servers.
In this tutorial, you'll learn how to build a LLM-powered chatbot client that connects to MCP servers. It helps to have gone through the [Server quickstart](/quickstart/server) that guides you through the basic of building your first server.
<Tabs>
<Tab title="Python">
[You can find the complete code for this tutorial here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client-python)
## System Requirements
Before starting, ensure your system meets these requirements:
* Mac or Windows computer
* Latest Python version installed
* Latest version of `uv` installed
## Setting Up Your Environment
First, create a new Python project with `uv`:
```bash
# Create project directory
uv init mcp-client
cd mcp-client
# Create virtual environment
uv venv
# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On Unix or MacOS:
source .venv/bin/activate
# Install required packages
uv add mcp anthropic python-dotenv
# Remove boilerplate files
rm hello.py
# Create our main file
touch client.py
```
## Setting Up Your API Key
You'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/settings/keys).
Create a `.env` file to store it:
```bash
# Create .env file
touch .env
```
Add your key to the `.env` file:
```bash
ANTHROPIC_API_KEY=<your key here>
```
Add `.env` to your `.gitignore`:
```bash
echo ".env" >> .gitignore
```
<Warning>
Make sure you keep your `ANTHROPIC_API_KEY` secure!
</Warning>
## Creating the Client
### Basic Client Structure
First, let's set up our imports and create the basic client class:
```python
import asyncio
from typing import Optional
from contextlib import AsyncExitStack
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from anthropic import Anthropic
from dotenv import load_dotenv
load_dotenv() # load environment variables from .env
class MCPClient:
def __init__(self):
# Initialize session and client objects
self.session: Optional[ClientSession] = None
self.exit_stack = AsyncExitStack()
self.anthropic = Anthropic()
# methods will go here
```
### Server Connection Management
Next, we'll implement the method to connect to an MCP server:
```python
async def connect_to_server(self, server_script_path: str):
"""Connect to an MCP server
Args:
server_script_path: Path to the server script (.py or .js)
"""
is_python = server_script_path.endswith('.py')
is_js = server_script_path.endswith('.js')
if not (is_python or is_js):
raise ValueError("Server script must be a .py or .js file")
command = "python" if is_python else "node"
server_params = StdioServerParameters(
command=command,
args=[server_script_path],
env=None
)
stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
self.stdio, self.write = stdio_transport
self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))
await self.session.initialize()
# List available tools
response = await self.session.list_tools()
tools = response.tools
print("\nConnected to server with tools:", [tool.name for tool in tools])
```
### Query Processing Logic
Now let's add the core functionality for processing queries and handling tool calls:
```python
async def process_query(self, query: str) -> str:
"""Process a query using Claude and available tools"""
messages = [
{
"role": "user",
"content": query
}
]
response = await self.session.list_tools()
available_tools = [{
"name": tool.name,
"description": tool.description,
"input_schema": tool.inputSchema
} for tool in response.tools]
# Initial Claude API call
response = self.anthropic.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1000,
messages=messages,
tools=available_tools
)
# Process response and handle tool calls
final_text = []
assistant_message_content = []
for content in response.content:
if content.type == 'text':
final_text.append(content.text)
assistant_message_content.append(content)
elif content.type == 'tool_use':
tool_name = content.name
tool_args = content.input
# Execute tool call
result = await self.session.call_tool(tool_name, tool_args)
final_text.append(f"[Calling tool {tool_name} with args {tool_args}]")
assistant_message_content.append(content)
messages.append({
"role": "assistant",
"content": assistant_message_content
})
messages.append({
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": content.id,
"content": result.content
}
]
})
# Get next response from Claude
response = self.anthropic.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1000,
messages=messages,
tools=available_tools
)
final_text.append(response.content[0].text)
return "\n".join(final_text)
```
### Interactive Chat Interface
Now we'll add the chat loop and cleanup functionality:
```python
async def chat_loop(self):
"""Run an interactive chat loop"""
print("\nMCP Client Started!")
print("Type your queries or 'quit' to exit.")
while True:
try:
query = input("\nQuery: ").strip()
if query.lower() == 'quit':
break
response = await self.process_query(query)
print("\n" + response)
except Exception as e:
print(f"\nError: {str(e)}")
async def cleanup(self):
"""Clean up resources"""
await self.exit_stack.aclose()
```
### Main Entry Point
Finally, we'll add the main execution logic:
```python
async def main():
if len(sys.argv) < 2:
print("Usage: python client.py <path_to_server_script>")
sys.exit(1)
client = MCPClient()
try:
await client.connect_to_server(sys.argv[1])
await client.chat_loop()
finally:
await client.cleanup()
if __name__ == "__main__":
import sys
asyncio.run(main())
```
You can find the complete `client.py` file [here.](https://gist.github.com/zckly/f3f28ea731e096e53b39b47bf0a2d4b1)
## Key Components Explained
### 1. Client Initialization
* The `MCPClient` class initializes with session management and API clients
* Uses `AsyncExitStack` for proper resource management
* Configures the Anthropic client for Claude interactions
### 2. Server Connection
* Supports both Python and Node.js servers
* Validates server script type
* Sets up proper communication channels
* Initializes the session and lists available tools
### 3. Query Processing
* Maintains conversation context
* Handles Claude's responses and tool calls
* Manages the message flow between Claude and tools
* Combines results into a coherent response
### 4. Interactive Interface
* Provides a simple command-line interface
* Handles user input and displays responses
* Includes basic error handling
* Allows graceful exit
### 5. Resource Management
* Proper cleanup of resources
* Error handling for connection issues
* Graceful shutdown procedures
## Common Customization Points
1. **Tool Handling**
* Modify `process_query()` to handle specific tool types
* Add custom error handling for tool calls
* Implement tool-specific response formatting
2. **Response Processing**
* Customize how tool results are formatted
* Add response filtering or transformation
* Implement custom logging
3. **User Interface**
* Add a GUI or web interface
* Implement rich console output
* Add command history or auto-completion
## Running the Client
To run your client with any MCP server:
```bash
uv run client.py path/to/server.py # python server
uv run client.py path/to/build/index.js # node server
```
<Note>
If you're continuing the weather tutorial from the server quickstart, your command might look something like this: `python client.py .../weather/src/weather/server.py`
</Note>
The client will:
1. Connect to the specified server
2. List available tools
3. Start an interactive chat session where you can:
* Enter queries
* See tool executions
* Get responses from Claude
Here's an example of what it should look like if connected to the weather server from the server quickstart:
<Frame>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/client-claude-cli-python.png" />
</Frame>
## How It Works
When you submit a query:
1. The client gets the list of available tools from the server
2. Your query is sent to Claude along with tool descriptions
3. Claude decides which tools (if any) to use
4. The client executes any requested tool calls through the server
5. Results are sent back to Claude
6. Claude provides a natural language response
7. The response is displayed to you
## Best practices
1. **Error Handling**
* Always wrap tool calls in try-catch blocks
* Provide meaningful error messages
* Gracefully handle connection issues
2. **Resource Management**
* Use `AsyncExitStack` for proper cleanup
* Close connections when done
* Handle server disconnections
3. **Security**
* Store API keys securely in `.env`
* Validate server responses
* Be cautious with tool permissions
## Troubleshooting
### Server Path Issues
* Double-check the path to your server script is correct
* Use the absolute path if the relative path isn't working
* For Windows users, make sure to use forward slashes (/) or escaped backslashes (\\) in the path
* Verify the server file has the correct extension (.py for Python or .js for Node.js)
Example of correct path usage:
```bash
# Relative path
uv run client.py ./server/weather.py
# Absolute path
uv run client.py /Users/username/projects/mcp-server/weather.py
# Windows path (either format works)
uv run client.py C:/projects/mcp-server/weather.py
uv run client.py C:\\projects\\mcp-server\\weather.py
```
### Response Timing
* The first response might take up to 30 seconds to return
* This is normal and happens while:
* The server initializes
* Claude processes the query
* Tools are being executed
* Subsequent responses are typically faster
* Don't interrupt the process during this initial waiting period
### Common Error Messages
If you see:
* `FileNotFoundError`: Check your server path
* `Connection refused`: Ensure the server is running and the path is correct
* `Tool execution failed`: Verify the tool's required environment variables are set
* `Timeout error`: Consider increasing the timeout in your client configuration
</Tab>
<Tab title="Node">
[You can find the complete code for this tutorial here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client-typescript)
## System Requirements
Before starting, ensure your system meets these requirements:
* Mac or Windows computer
* Node.js 16 or higher installed
* Latest version of `npm` installed
* Anthropic API key (Claude)
## Setting Up Your Environment
First, let's create and set up our project:
<CodeGroup>
```bash MacOS/Linux
# Create project directory
mkdir mcp-client-typescript
cd mcp-client-typescript
# Initialize npm project
npm init -y
# Install dependencies
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv
# Install dev dependencies
npm install -D @types/node typescript
# Create source file
touch index.ts
```
```powershell Windows
# Create project directory
md mcp-client-typescript
cd mcp-client-typescript
# Initialize npm project
npm init -y
# Install dependencies
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv
# Install dev dependencies
npm install -D @types/node typescript
# Create source file
new-item index.ts
```
</CodeGroup>
Update your `package.json` to set `type: "module"` and a build script:
```json package.json
{
"type": "module",
"scripts": {
"build": "tsc && chmod 755 build/index.js"
}
}
```
Create a `tsconfig.json` in the root of your project:
```json tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["index.ts"],
"exclude": ["node_modules"]
}
```
## Setting Up Your API Key
You'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/settings/keys).
Create a `.env` file to store it:
```bash
echo "ANTHROPIC_API_KEY=<your key here>" > .env
```
Add `.env` to your `.gitignore`:
```bash
echo ".env" >> .gitignore
```
<Warning>
Make sure you keep your `ANTHROPIC_API_KEY` secure!
</Warning>
## Creating the Client
### Basic Client Structure
First, let's set up our imports and create the basic client class in `index.ts`:
```typescript
import { Anthropic } from "@anthropic-ai/sdk";
import {
MessageParam,
Tool,
} from "@anthropic-ai/sdk/resources/messages/messages.mjs";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import readline from "readline/promises";
import dotenv from "dotenv";
dotenv.config();
const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
if (!ANTHROPIC_API_KEY) {
throw new Error("ANTHROPIC_API_KEY is not set");
}
class MCPClient {
private mcp: Client;
private anthropic: Anthropic;
private transport: StdioClientTransport | null = null;
private tools: Tool[] = [];
constructor() {
this.anthropic = new Anthropic({
apiKey: ANTHROPIC_API_KEY,
});
this.mcp = new Client({ name: "mcp-client-cli", version: "1.0.0" });
}
// methods will go here
}
```
### Server Connection Management
Next, we'll implement the method to connect to an MCP server:
```typescript
async connectToServer(serverScriptPath: string) {
try {
const isJs = serverScriptPath.endsWith(".js");
const isPy = serverScriptPath.endsWith(".py");
if (!isJs && !isPy) {
throw new Error("Server script must be a .js or .py file");
}
const command = isPy
? process.platform === "win32"
? "python"
: "python3"
: process.execPath;
this.transport = new StdioClientTransport({
command,
args: [serverScriptPath],
});
this.mcp.connect(this.transport);
const toolsResult = await this.mcp.listTools();
this.tools = toolsResult.tools.map((tool) => {
return {
name: tool.name,
description: tool.description,
input_schema: tool.inputSchema,
};
});
console.log(
"Connected to server with tools:",
this.tools.map(({ name }) => name)
);
} catch (e) {
console.log("Failed to connect to MCP server: ", e);
throw e;
}
}
```
### Query Processing Logic
Now let's add the core functionality for processing queries and handling tool calls:
```typescript
async processQuery(query: string) {
const messages: MessageParam[] = [
{
role: "user",
content: query,
},
];
const response = await this.anthropic.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1000,
messages,
tools: this.tools,
});
const finalText = [];
const toolResults = [];
for (const content of response.content) {
if (content.type === "text") {
finalText.push(content.text);
} else if (content.type === "tool_use") {
const toolName = content.name;
const toolArgs = content.input as { [x: string]: unknown } | undefined;
const result = await this.mcp.callTool({
name: toolName,
arguments: toolArgs,
});
toolResults.push(result);
finalText.push(
`[Calling tool ${toolName} with args ${JSON.stringify(toolArgs)}]`
);
messages.push({
role: "user",
content: result.content as string,
});
const response = await this.anthropic.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1000,
messages,
});
finalText.push(
response.content[0].type === "text" ? response.content[0].text : ""
);
}
}
return finalText.join("\n");
}
```
### Interactive Chat Interface
Now we'll add the chat loop and cleanup functionality:
```typescript
async chatLoop() {
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout,
});
try {
console.log("\nMCP Client Started!");
console.log("Type your queries or 'quit' to exit.");
while (true) {
const message = await rl.question("\nQuery: ");
if (message.toLowerCase() === "quit") {
break;
}
const response = await this.processQuery(message);
console.log("\n" + response);
}
} finally {
rl.close();
}
}
async cleanup() {
await this.mcp.close();
}
```
### Main Entry Point
Finally, we'll add the main execution logic:
```typescript
async function main() {
if (process.argv.length < 3) {
console.log("Usage: node index.ts <path_to_server_script>");
return;
}
const mcpClient = new MCPClient();
try {
await mcpClient.connectToServer(process.argv[2]);
await mcpClient.chatLoop();
} finally {
await mcpClient.cleanup();
process.exit(0);
}
}
main();
```
## Running the Client
To run your client with any MCP server:
```bash
# Build TypeScript
npm run build
# Run the client
node build/index.js path/to/server.py # python server
node build/index.js path/to/build/index.js # node server
```
<Note>
If you're continuing the weather tutorial from the server quickstart, your command might look something like this: `node build/index.js .../quickstart-resources/weather-server-typescript/build/index.js`
</Note>
**The client will:**
1. Connect to the specified server
2. List available tools
3. Start an interactive chat session where you can:
* Enter queries
* See tool executions
* Get responses from Claude
## How It Works
When you submit a query:
1. The client gets the list of available tools from the server
2. Your query is sent to Claude along with tool descriptions
3. Claude decides which tools (if any) to use
4. The client executes any requested tool calls through the server
5. Results are sent back to Claude
6. Claude provides a natural language response
7. The response is displayed to you
## Best practices
1. **Error Handling**
* Use TypeScript's type system for better error detection
* Wrap tool calls in try-catch blocks
* Provide meaningful error messages
* Gracefully handle connection issues
2. **Security**
* Store API keys securely in `.env`
* Validate server responses
* Be cautious with tool permissions
## Troubleshooting
### Server Path Issues
* Double-check the path to your server script is correct
* Use the absolute path if the relative path isn't working
* For Windows users, make sure to use forward slashes (/) or escaped backslashes (\\) in the path
* Verify the server file has the correct extension (.js for Node.js or .py for Python)
Example of correct path usage:
```bash
# Relative path
node build/index.js ./server/build/index.js
# Absolute path
node build/index.js /Users/username/projects/mcp-server/build/index.js
# Windows path (either format works)
node build/index.js C:/projects/mcp-server/build/index.js
node build/index.js C:\\projects\\mcp-server\\build\\index.js
```
### Response Timing
* The first response might take up to 30 seconds to return
* This is normal and happens while:
* The server initializes
* Claude processes the query
* Tools are being executed
* Subsequent responses are typically faster
* Don't interrupt the process during this initial waiting period
### Common Error Messages
If you see:
* `Error: Cannot find module`: Check your build folder and ensure TypeScript compilation succeeded
* `Connection refused`: Ensure the server is running and the path is correct
* `Tool execution failed`: Verify the tool's required environment variables are set
* `ANTHROPIC_API_KEY is not set`: Check your .env file and environment variables
* `TypeError`: Ensure you're using the correct types for tool arguments
</Tab>
<Tab title="Java">
<Note>
This is a quickstart demo based on Spring AI MCP auto-configuration and boot starters.
To learn how to create sync and async MCP Clients manually, consult the [Java SDK Client](/sdk/java/mcp-client) documentation
</Note>
This example demonstrates how to build an interactive chatbot that combines Spring AI's Model Context Protocol (MCP) with the [Brave Search MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search). The application creates a conversational interface powered by Anthropic's Claude AI model that can perform internet searches through Brave Search, enabling natural language interactions with real-time web data.
[You can find the complete code for this tutorial here.](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/web-search/brave-chatbot)
## System Requirements
Before starting, ensure your system meets these requirements:
* Java 17 or higher
* Maven 3.6+
* npx package manager
* Anthropic API key (Claude)
* Brave Search API key
## Setting Up Your Environment
1. Install npx (Node Package eXecute):
First, make sure to install [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
and then run:
```bash
npm install -g npx
```
2. Clone the repository:
```bash
git clone https://github.com/spring-projects/spring-ai-examples.git
cd model-context-protocol/brave-chatbot
```
3. Set up your API keys:
```bash
export ANTHROPIC_API_KEY='your-anthropic-api-key-here'
export BRAVE_API_KEY='your-brave-api-key-here'
```
4. Build the application:
```bash
./mvnw clean install
```
5. Run the application using Maven:
```bash
./mvnw spring-boot:run
```
<Warning>
Make sure you keep your `ANTHROPIC_API_KEY` and `BRAVE_API_KEY` keys secure!
</Warning>
## How it Works
The application integrates Spring AI with the Brave Search MCP server through several components:
### MCP Client Configuration
1. Required dependencies in pom.xml:
```xml
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-anthropic-spring-boot-starter</artifactId>
</dependency>
```
2. Application properties (application.yml):
```yml
spring:
ai:
mcp:
client:
enabled: true
name: brave-search-client
version: 1.0.0
type: SYNC
request-timeout: 20s
stdio:
root-change-notification: true
servers-configuration: classpath:/mcp-servers-config.json
anthropic:
api-key: ${ANTHROPIC_API_KEY}
```
This activates the `spring-ai-mcp-client-spring-boot-starter` to create one or more `McpClient`s based on the provided server configuration.
3. MCP Server Configuration (`mcp-servers-config.json`):
```json
{
"mcpServers": {
"brave-search": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-brave-search"
],
"env": {
"BRAVE_API_KEY": "<PUT YOUR BRAVE API KEY>"
}
}
}
}
```
### Chat Implementation
The chatbot is implemented using Spring AI's ChatClient with MCP tool integration:
```java
var chatClient = chatClientBuilder
.defaultSystem("You are useful assistant, expert in AI and Java.")
.defaultTools((Object[]) mcpToolAdapter.toolCallbacks())
.defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
.build();
```
Key features:
* Uses Claude AI model for natural language understanding
* Integrates Brave Search through MCP for real-time web search capabilities
* Maintains conversation memory using InMemoryChatMemory
* Runs as an interactive command-line application
### Build and run
```bash
./mvnw clean install
java -jar ./target/ai-mcp-brave-chatbot-0.0.1-SNAPSHOT.jar
```
or
```bash
./mvnw spring-boot:run
```
The application will start an interactive chat session where you can ask questions. The chatbot will use Brave Search when it needs to find information from the internet to answer your queries.
The chatbot can:
* Answer questions using its built-in knowledge
* Perform web searches when needed using Brave Search
* Remember context from previous messages in the conversation
* Combine information from multiple sources to provide comprehensive answers
### Advanced Configuration
The MCP client supports additional configuration options:
* Client customization through `McpSyncClientCustomizer` or `McpAsyncClientCustomizer`
* Multiple clients with multiple transport types: `STDIO` and `SSE` (Server-Sent Events)
* Integration with Spring AI's tool execution framework
* Automatic client initialization and lifecycle management
For WebFlux-based applications, you can use the WebFlux starter instead:
```xml
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-client-webflux-spring-boot-starter</artifactId>
</dependency>
```
This provides similar functionality but uses a WebFlux-based SSE transport implementation, recommended for production deployments.
</Tab>
</Tabs>
## Next steps
<CardGroup cols={2}>
<Card title="Example servers" icon="grid" href="/examples">
Check out our gallery of official MCP servers and implementations
</Card>
<Card title="Clients" icon="cubes" href="/clients">
View the list of clients that support MCP integrations
</Card>
<Card title="Building MCP with LLMs" icon="comments" href="/tutorials/building-mcp-with-llms">
Learn how to use LLMs like Claude to speed up your MCP development
</Card>
<Card title="Core architecture" icon="sitemap" href="/docs/concepts/architecture">
Understand how MCP connects clients, servers, and LLMs
</Card>
</CardGroup>
# For Server Developers
Source: https://modelcontextprotocol.io/quickstart/server
Get started building your own server to use in Claude for Desktop and other clients.
In this tutorial, we'll build a simple MCP weather server and connect it to a host, Claude for Desktop. We'll start with a basic setup, and then progress to more complex use cases.
### What we'll be building
Many LLMs (including Claude) do not currently have the ability to fetch the forecast and severe weather alerts. Let's use MCP to solve that!
We'll build a server that exposes two tools: `get-alerts` and `get-forecast`. Then we'll connect the server to an MCP host (in this case, Claude for Desktop):
<Frame>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/weather-alerts.png" />
</Frame>
<Frame>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/current-weather.png" />
</Frame>
<Note>
Servers can connect to any client. We've chosen Claude for Desktop here for simplicity, but we also have guides on [building your own client](/quickstart/client) as well as a [list of other clients here](/clients).
</Note>
<Accordion title="Why Claude for Desktop and not Claude.ai?">
Because servers are locally run, MCP currently only supports desktop hosts. Remote hosts are in active development.
</Accordion>
### Core MCP Concepts
MCP servers can provide three main types of capabilities:
1. **Resources**: File-like data that can be read by clients (like API responses or file contents)
2. **Tools**: Functions that can be called by the LLM (with user approval)
3. **Prompts**: Pre-written templates that help users accomplish specific tasks
This tutorial will primarily focus on tools.
<Tabs>
<Tab title="Python">
Let's get started with building our weather server! [You can find the complete code for what we'll be building here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-python)
### Prerequisite knowledge
This quickstart assumes you have familiarity with:
* Python
* LLMs like Claude
### System requirements
* Python 3.10 or higher installed.
* You must use the Python MCP SDK 1.2.0 or higher.
### Set up your environment
First, let's install `uv` and set up our Python project and environment:
<CodeGroup>
```bash MacOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```
```powershell Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
</CodeGroup>
Make sure to restart your terminal afterwards to ensure that the `uv` command gets picked up.
Now, let's create and set up our project:
<CodeGroup>
```bash MacOS/Linux
# Create a new directory for our project
uv init weather
cd weather
# Create virtual environment and activate it
uv venv
source .venv/bin/activate
# Install dependencies
uv add "mcp[cli]" httpx
# Create our server file
touch weather.py
```
```powershell Windows
# Create a new directory for our project
uv init weather
cd weather
# Create virtual environment and activate it
uv venv
.venv\Scripts\activate
# Install dependencies
uv add mcp[cli] httpx
# Create our server file
new-item weather.py
```
</CodeGroup>
Now let's dive into building your server.
## Building your server
### Importing packages and setting up the instance
Add these to the top of your `weather.py`:
```python
from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP
# Initialize FastMCP server
mcp = FastMCP("weather")
# Constants
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"
```
The FastMCP class uses Python type hints and docstrings to automatically generate tool definitions, making it easy to create and maintain MCP tools.
### Helper functions
Next, let's add our helper functions for querying and formatting the data from the National Weather Service API:
```python
async def make_nws_request(url: str) -> dict[str, Any] | None:
"""Make a request to the NWS API with proper error handling."""
headers = {
"User-Agent": USER_AGENT,
"Accept": "application/geo+json"
}
async with httpx.AsyncClient() as client:
try:
response = await client.get(url, headers=headers, timeout=30.0)
response.raise_for_status()
return response.json()
except Exception:
return None
def format_alert(feature: dict) -> str:
"""Format an alert feature into a readable string."""
props = feature["properties"]
return f"""
Event: {props.get('event', 'Unknown')}
Area: {props.get('areaDesc', 'Unknown')}
Severity: {props.get('severity', 'Unknown')}
Description: {props.get('description', 'No description available')}
Instructions: {props.get('instruction', 'No specific instructions provided')}
"""
```
### Implementing tool execution
The tool execution handler is responsible for actually executing the logic of each tool. Let's add it:
```python
@mcp.tool()
async def get_alerts(state: str) -> str:
"""Get weather alerts for a US state.
Args:
state: Two-letter US state code (e.g. CA, NY)
"""
url = f"{NWS_API_BASE}/alerts/active/area/{state}"
data = await make_nws_request(url)
if not data or "features" not in data:
return "Unable to fetch alerts or no alerts found."
if not data["features"]:
return "No active alerts for this state."
alerts = [format_alert(feature) for feature in data["features"]]
return "\n---\n".join(alerts)
@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
"""Get weather forecast for a location.
Args:
latitude: Latitude of the location
longitude: Longitude of the location
"""
# First get the forecast grid endpoint
points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
points_data = await make_nws_request(points_url)
if not points_data:
return "Unable to fetch forecast data for this location."
# Get the forecast URL from the points response
forecast_url = points_data["properties"]["forecast"]
forecast_data = await make_nws_request(forecast_url)
if not forecast_data:
return "Unable to fetch detailed forecast."
# Format the periods into a readable forecast
periods = forecast_data["properties"]["periods"]
forecasts = []
for period in periods[:5]: # Only show next 5 periods
forecast = f"""
{period['name']}:
Temperature: {period['temperature']}°{period['temperatureUnit']}
Wind: {period['windSpeed']} {period['windDirection']}
Forecast: {period['detailedForecast']}
"""
forecasts.append(forecast)
return "\n---\n".join(forecasts)
```
### Running the server
Finally, let's initialize and run the server:
```python
if __name__ == "__main__":
# Initialize and run the server
mcp.run(transport='stdio')
```
Your server is complete! Run `uv run weather.py` to confirm that everything's working.
Let's now test your server from an existing MCP host, Claude for Desktop.
## Testing your server with Claude for Desktop
<Note>
Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/quickstart/client) tutorial to build an MCP client that connects to the server we just built.
</Note>
First, make sure you have Claude for Desktop installed. [You can install the latest version
here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
We'll need to configure Claude for Desktop for whichever MCP servers you want to use. To do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor. Make sure to create the file if it doesn't exist.
For example, if you have [VS Code](https://code.visualstudio.com/) installed:
<Tabs>
<Tab title="MacOS/Linux">
```bash
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
</Tab>
<Tab title="Windows">
```powershell
code $env:AppData\Claude\claude_desktop_config.json
```
</Tab>
</Tabs>
You'll then add your servers in the `mcpServers` key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.
In this case, we'll add our single weather server like so:
<Tabs>
<Tab title="MacOS/Linux">
```json Python
{
"mcpServers": {
"weather": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
"run",
"weather.py"
]
}
}
}
```
</Tab>
<Tab title="Windows">
```json Python
{
"mcpServers": {
"weather": {
"command": "uv",
"args": [
"--directory",
"C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather",
"run",
"weather.py"
]
}
}
}
```
</Tab>
</Tabs>
<Warning>
You may need to put the full path to the `uv` executable in the `command` field. You can get this by running `which uv` on MacOS/Linux or `where uv` on Windows.
</Warning>
<Note>
Make sure you pass in the absolute path to your server.
</Note>
This tells Claude for Desktop:
1. There's an MCP server named "weather"
2. To launch it by running `uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather.py`
Save the file, and restart **Claude for Desktop**.
</Tab>
<Tab title="Node">
Let's get started with building our weather server! [You can find the complete code for what we'll be building here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-typescript)
### Prerequisite knowledge
This quickstart assumes you have familiarity with:
* TypeScript
* LLMs like Claude
### System requirements
For TypeScript, make sure you have the latest version of Node installed.
### Set up your environment
First, let's install Node.js and npm if you haven't already. You can download them from [nodejs.org](https://nodejs.org/).
Verify your Node.js installation:
```bash
node --version
npm --version
```
For this tutorial, you'll need Node.js version 16 or higher.
Now, let's create and set up our project:
<CodeGroup>
```bash MacOS/Linux
# Create a new directory for our project
mkdir weather
cd weather
# Initialize a new npm project
npm init -y
# Install dependencies
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript
# Create our files
mkdir src
touch src/index.ts
```
```powershell Windows
# Create a new directory for our project
md weather
cd weather
# Initialize a new npm project
npm init -y
# Install dependencies
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript
# Create our files
md src
new-item src\index.ts
```
</CodeGroup>
Update your package.json to add type: "module" and a build script:
```json package.json
{
"type": "module",
"bin": {
"weather": "./build/index.js"
},
"scripts": {
"build": "tsc && chmod 755 build/index.js"
},
"files": [
"build"
],
}
```
Create a `tsconfig.json` in the root of your project:
```json tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
```
Now let's dive into building your server.
## Building your server
### Importing packages and setting up the instance
Add these to the top of your `src/index.ts`:
```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const NWS_API_BASE = "https://api.weather.gov";
const USER_AGENT = "weather-app/1.0";
// Create server instance
const server = new McpServer({
name: "weather",
version: "1.0.0",
});
```
### Helper functions
Next, let's add our helper functions for querying and formatting the data from the National Weather Service API:
```typescript
// Helper function for making NWS API requests
async function makeNWSRequest<T>(url: string): Promise<T | null> {
const headers = {
"User-Agent": USER_AGENT,
Accept: "application/geo+json",
};
try {
const response = await fetch(url, { headers });
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return (await response.json()) as T;
} catch (error) {
console.error("Error making NWS request:", error);
return null;
}
}
interface AlertFeature {
properties: {
event?: string;
areaDesc?: string;
severity?: string;
status?: string;
headline?: string;
};
}
// Format alert data
function formatAlert(feature: AlertFeature): string {
const props = feature.properties;
return [
`Event: ${props.event || "Unknown"}`,
`Area: ${props.areaDesc || "Unknown"}`,
`Severity: ${props.severity || "Unknown"}`,
`Status: ${props.status || "Unknown"}`,
`Headline: ${props.headline || "No headline"}`,
"---",
].join("\n");
}
interface ForecastPeriod {
name?: string;
temperature?: number;
temperatureUnit?: string;
windSpeed?: string;
windDirection?: string;
shortForecast?: string;
}
interface AlertsResponse {
features: AlertFeature[];
}
interface PointsResponse {
properties: {
forecast?: string;
};
}
interface ForecastResponse {
properties: {
periods: ForecastPeriod[];
};
}
```
### Implementing tool execution
The tool execution handler is responsible for actually executing the logic of each tool. Let's add it:
```typescript
// Register weather tools
server.tool(
"get-alerts",
"Get weather alerts for a state",
{
state: z.string().length(2).describe("Two-letter state code (e.g. CA, NY)"),
},
async ({ state }) => {
const stateCode = state.toUpperCase();
const alertsUrl = `${NWS_API_BASE}/alerts?area=${stateCode}`;
const alertsData = await makeNWSRequest<AlertsResponse>(alertsUrl);
if (!alertsData) {
return {
content: [
{
type: "text",
text: "Failed to retrieve alerts data",
},
],
};
}
const features = alertsData.features || [];
if (features.length === 0) {
return {
content: [
{
type: "text",
text: `No active alerts for ${stateCode}`,
},
],
};
}
const formattedAlerts = features.map(formatAlert);
const alertsText = `Active alerts for ${stateCode}:\n\n${formattedAlerts.join("\n")}`;
return {
content: [
{
type: "text",
text: alertsText,
},
],
};
},
);
server.tool(
"get-forecast",
"Get weather forecast for a location",
{
latitude: z.number().min(-90).max(90).describe("Latitude of the location"),
longitude: z.number().min(-180).max(180).describe("Longitude of the location"),
},
async ({ latitude, longitude }) => {
// Get grid point data
const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`;
const pointsData = await makeNWSRequest<PointsResponse>(pointsUrl);
if (!pointsData) {
return {
content: [
{
type: "text",
text: `Failed to retrieve grid point data for coordinates: ${latitude}, ${longitude}. This location may not be supported by the NWS API (only US locations are supported).`,
},
],
};
}
const forecastUrl = pointsData.properties?.forecast;
if (!forecastUrl) {
return {
content: [
{
type: "text",
text: "Failed to get forecast URL from grid point data",
},
],
};
}
// Get forecast data
const forecastData = await makeNWSRequest<ForecastResponse>(forecastUrl);
if (!forecastData) {
return {
content: [
{
type: "text",
text: "Failed to retrieve forecast data",
},
],
};
}
const periods = forecastData.properties?.periods || [];
if (periods.length === 0) {
return {
content: [
{
type: "text",
text: "No forecast periods available",
},
],
};
}
// Format forecast periods
const formattedForecast = periods.map((period: ForecastPeriod) =>
[
`${period.name || "Unknown"}:`,
`Temperature: ${period.temperature || "Unknown"}°${period.temperatureUnit || "F"}`,
`Wind: ${period.windSpeed || "Unknown"} ${period.windDirection || ""}`,
`${period.shortForecast || "No forecast available"}`,
"---",
].join("\n"),
);
const forecastText = `Forecast for ${latitude}, ${longitude}:\n\n${formattedForecast.join("\n")}`;
return {
content: [
{
type: "text",
text: forecastText,
},
],
};
},
);
```
### Running the server
Finally, implement the main function to run the server:
```typescript
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Weather MCP Server running on stdio");
}
main().catch((error) => {
console.error("Fatal error in main():", error);
process.exit(1);
});
```
Make sure to run `npm run build` to build your server! This is a very important step in getting your server to connect.
Let's now test your server from an existing MCP host, Claude for Desktop.
## Testing your server with Claude for Desktop
<Note>
Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/quickstart/client) tutorial to build an MCP client that connects to the server we just built.
</Note>
First, make sure you have Claude for Desktop installed. [You can install the latest version
here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
We'll need to configure Claude for Desktop for whichever MCP servers you want to use. To do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor. Make sure to create the file if it doesn't exist.
For example, if you have [VS Code](https://code.visualstudio.com/) installed:
<Tabs>
<Tab title="MacOS/Linux">
```bash
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
</Tab>
<Tab title="Windows">
```powershell
code $env:AppData\Claude\claude_desktop_config.json
```
</Tab>
</Tabs>
You'll then add your servers in the `mcpServers` key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.
In this case, we'll add our single weather server like so:
<Tabs>
<Tab title="MacOS/Linux">
<CodeGroup>
```json Node
{
"mcpServers": {
"weather": {
"command": "node",
"args": [
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js"
]
}
}
}
```
</CodeGroup>
</Tab>
<Tab title="Windows">
<CodeGroup>
```json Node
{
"mcpServers": {
"weather": {
"command": "node",
"args": [
"C:\\PATH\\TO\\PARENT\\FOLDER\\weather\\build\\index.js"
]
}
}
}
```
</CodeGroup>
</Tab>
</Tabs>
This tells Claude for Desktop:
1. There's an MCP server named "weather"
2. Launch it by running `node /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js`
Save the file, and restart **Claude for Desktop**.
</Tab>
<Tab title="Java">
<Note>
This is a quickstart demo based on Spring AI MCP auto-configuration and boot starters.
To learn how to create sync and async MCP Servers, manually, consult the [Java SDK Server](/sdk/java/mcp-server) documentation.
</Note>
Let's get started with building our weather server!
[You can find the complete code for what we'll be building here.](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-stdio-server)
For more information, see the [MCP Server Boot Starter](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html) reference documentation.
For manual MCP Server implementation, refer to the [MCP Server Java SDK documentation](/sdk/java/mcp-server).
### System requirements
* Java 17 or higher installed.
* [Spring Boot 3.3.x](https://docs.spring.io/spring-boot/installing.html) or higher
### Set up your environment
Use the [Spring Initizer](https://start.spring.io/) to bootstrat the project.
You will need to add the following dependencies:
<Tabs>
<Tab title="Maven">
```xml
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-web</artifactId>
</dependency>
</dependencies>
```
</Tab>
<Tab title="Gradle">
```groovy
dependencies {
implementation platform("org.springframework.ai:spring-ai-mcp-server-spring-boot-starter")
implementation platform("org.springframework:spring-web")
}
```
</Tab>
</Tabs>
Then configure your application by setting the applicaiton properties:
<CodeGroup>
```bash application.properties
spring.main.bannerMode=off
logging.pattern.console=
```
```yaml application.yml
logging:
pattern:
console:
spring:
main:
banner-mode: off
```
</CodeGroup>
The [Server Configuration Properties](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html#_configuration_properties) documents all available properties.
Now let's dive into building your server.
## Building your server
### Weather Service
Let's implement a [WeatheService.java](https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter-stdio-server/src/main/java/org/springframework/ai/mcp/sample/server/WeatherService.java) that uses a REST client to query the data from the National Weather Service API:
```java
@Service
public class WeatherService {
private final RestClient restClient;
public WeatherService() {
this.restClient = RestClient.builder()
.baseUrl("https://api.weather.gov")
.defaultHeader("Accept", "application/geo+json")
.defaultHeader("User-Agent", "WeatherApiClient/1.0 (your@email.com)")
.build();
}
@Tool(description = "Get weather forecast for a specific latitude/longitude")
public String getWeatherForecastByLocation(
double latitude, // Latitude coordinate
double longitude // Longitude coordinate
) {
// Returns detailed forecast including:
// - Temperature and unit
// - Wind speed and direction
// - Detailed forecast description
}
@Tool(description = "Get weather alerts for a US state")
public String getAlerts(
@ToolParam(description = "Two-letter US state code (e.g. CA, NY") String state)
) {
// Returns active alerts including:
// - Event type
// - Affected area
// - Severity
// - Description
// - Safety instructions
}
// ......
}
```
The `@Service` annotation with auto-register the service in your applicaiton context.
The Spring AI `@Tool` annotation, making it easy to create and maintain MCP tools.
The auto-configuration will automatically register these tools with the MCP server.
### Create your Boot Applicaiton
```java
@SpringBootApplication
public class McpServerApplication {
public static void main(String[] args) {
SpringApplication.run(McpServerApplication.class, args);
}
@Bean
public ToolCallbackProvider weatherTools(WeatherService weatherService) {
return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
}
}
```
Uses the the `MethodToolCallbackProvider` utils to convert the `@Tools` into actionalble callbackes used by the MCP server.
### Running the server
Finally, let's build the server:
```bash
./mvnw clean install
```
This will generate a `mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar` file within the `target` folder.
Let's now test your server from an existing MCP host, Claude for Desktop.
## Testing your server with Claude for Desktop
<Note>
Claude for Desktop is not yet available on Linux.
</Note>
First, make sure you have Claude for Desktop installed.
[You can install the latest version here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
We'll need to configure Claude for Desktop for whichever MCP servers you want to use.
To do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor.
Make sure to create the file if it doesn't exist.
For example, if you have [VS Code](https://code.visualstudio.com/) installed:
<Tabs>
<Tab title="MacOS/Linux">
```bash
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
</Tab>
<Tab title="Windows">
```powershell
code $env:AppData\Claude\claude_desktop_config.json
```
</Tab>
</Tabs>
You'll then add your servers in the `mcpServers` key.
The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.
In this case, we'll add our single weather server like so:
<Tabs>
<Tab title="MacOS/Linux">
```json java
{
"mcpServers": {
"spring-ai-mcp-weather": {
"command": "java",
"args": [
"-Dspring.ai.mcp.server.stdio=true",
"-jar",
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
]
}
}
}
```
</Tab>
<Tab title="Windows">
```json java
{
"mcpServers": {
"spring-ai-mcp-weather": {
"command": "java",
"args": [
"-Dspring.ai.mcp.server.transport=STDIO",
"-jar",
"C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather\\mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
]
}
}
}
```
</Tab>
</Tabs>
<Note>
Make sure you pass in the absolute path to your server.
</Note>
This tells Claude for Desktop:
1. There's an MCP server named "my-weather-server"
2. To launch it by running `java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar`
Save the file, and restart **Claude for Desktop**.
## Testing your server with Java client
### Create a MCP Client manually
Use the `McpClient` to connect to the server:
```java
var stdioParams = ServerParameters.builder("java")
.args("-jar", "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar")
.build();
var stdioTransport = new StdioClientTransport(stdioParams);
var mcpClient = McpClient.sync(stdioTransport).build();
mcpClient.initialize();
ListToolsResult toolsList = mcpClient.listTools();
CallToolResult weather = mcpClient.callTool(
new CallToolRequest("getWeatherForecastByLocation",
Map.of("latitude", "47.6062", "longitude", "-122.3321")));
CallToolResult alert = mcpClient.callTool(
new CallToolRequest("getAlerts", Map.of("state", "NY")));
mcpClient.closeGracefully();
```
### Use MCP Client Boot Starter
Create a new boot starter applicaiton using the `spring-ai-mcp-client-spring-boot-starter` dependency:
```xml
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
</dependency>
```
and set the `spring.ai.mcp.client.stdio.servers-configuration` property to point to your `claude_desktop_config.json`.
You can re-use the existing Anthropic Destop configuration:
```properties
spring.ai.mcp.client.stdio.servers-configuration=file:PATH/TO/claude_desktop_config.json
```
When you stasrt your client applicaiton, the auto-configuration will create, automatically MCP clients from the claude\_desktop\_config.json.
For more information, see the [MCP Client Boot Starters](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-client-docs.html) reference documentation.
## More Java MCP Server examples
The [starter-webflux-server](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-webflux-server) demonstrates how to create a MCP server using SSE transport.
It showcases how to define and register MCP Tools, Resources, and Prompts, using the Spring Boot's auto-configuration capabilities.
</Tab>
</Tabs>
### Test with commands
Let's make sure Claude for Desktop is picking up the two tools we've exposed in our `weather` server. You can do this by looking for the hammer <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon:
<Frame>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/visual-indicator-mcp-tools.png" />
</Frame>
After clicking on the hammer icon, you should see two tools listed:
<Frame>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/available-mcp-tools.png" />
</Frame>
If your server isn't being picked up by Claude for Desktop, proceed to the [Troubleshooting](#troubleshooting) section for debugging tips.
If the hammer icon has shown up, you can now test your server by running the following commands in Claude for Desktop:
* What's the weather in Sacramento?
* What are the active weather alerts in Texas?
<Frame>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/current-weather.png" />
</Frame>
<Frame>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/weather-alerts.png" />
</Frame>
<Note>
Since this is the US National Weather service, the queries will only work for US locations.
</Note>
## What's happening under the hood
When you ask a question:
1. The client sends your question to Claude
2. Claude analyzes the available tools and decides which one(s) to use
3. The client executes the chosen tool(s) through the MCP server
4. The results are sent back to Claude
5. Claude formulates a natural language response
6. The response is displayed to you!
## Troubleshooting
<AccordionGroup>
<Accordion title="Claude for Desktop Integration Issues">
**Getting logs from Claude for Desktop**
Claude.app logging related to MCP is written to log files in `~/Library/Logs/Claude`:
* `mcp.log` will contain general logging about MCP connections and connection failures.
* Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server.
You can run the following command to list recent logs and follow along with any new ones:
```bash
# Check Claude's logs for errors
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
```
**Server not showing up in Claude**
1. Check your `claude_desktop_config.json` file syntax
2. Make sure the path to your project is absolute and not relative
3. Restart Claude for Desktop completely
**Tool calls failing silently**
If Claude attempts to use the tools but they fail:
1. Check Claude's logs for errors
2. Verify your server builds and runs without errors
3. Try restarting Claude for Desktop
**None of this is working. What do I do?**
Please refer to our [debugging guide](/docs/tools/debugging) for better debugging tools and more detailed guidance.
</Accordion>
<Accordion title="Weather API Issues">
**Error: Failed to retrieve grid point data**
This usually means either:
1. The coordinates are outside the US
2. The NWS API is having issues
3. You're being rate limited
Fix:
* Verify you're using US coordinates
* Add a small delay between requests
* Check the NWS API status page
**Error: No active alerts for \[STATE]**
This isn't an error - it just means there are no current weather alerts for that state. Try a different state or check during severe weather.
</Accordion>
</AccordionGroup>
<Note>
For more advanced troubleshooting, check out our guide on [Debugging MCP](/docs/tools/debugging)
</Note>
## Next steps
<CardGroup cols={2}>
<Card title="Building a client" icon="outlet" href="/quickstart/client">
Learn how to build your own MCP client that can connect to your server
</Card>
<Card title="Example servers" icon="grid" href="/examples">
Check out our gallery of official MCP servers and implementations
</Card>
<Card title="Debugging Guide" icon="bug" href="/docs/tools/debugging">
Learn how to effectively debug MCP servers and integrations
</Card>
<Card title="Building MCP with LLMs" icon="comments" href="/tutorials/building-mcp-with-llms">
Learn how to use LLMs like Claude to speed up your MCP development
</Card>
</CardGroup>
# For Claude Desktop Users
Source: https://modelcontextprotocol.io/quickstart/user
Get started using pre-built servers in Claude for Desktop.
In this tutorial, you will extend [Claude for Desktop](https://claude.ai/download) so that it can read from your computer's file system, write new files, move files, and even search files.
<Frame>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-filesystem.png" />
</Frame>
Don't worry — it will ask you for your permission before executing these actions!
## 1. Download Claude for Desktop
Start by downloading [Claude for Desktop](https://claude.ai/download), choosing either macOS or Windows. (Linux is not yet supported for Claude for Desktop.)
Follow the installation instructions.
If you already have Claude for Desktop, make sure it's on the latest version by clicking on the Claude menu on your computer and selecting "Check for Updates..."
<Accordion title="Why Claude for Desktop and not Claude.ai?">
Because servers are locally run, MCP currently only supports desktop hosts. Remote hosts are in active development.
</Accordion>
## 2. Add the Filesystem MCP Server
To add this filesystem functionality, we will be installing a pre-built [Filesystem MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) to Claude for Desktop. This is one of dozens of [servers](https://github.com/modelcontextprotocol/servers/tree/main) created by Anthropic and the community.
Get started by opening up the Claude menu on your computer and select "Settings..." Please note that these are not the Claude Account Settings found in the app window itself.
This is what it should look like on a Mac:
<Frame style={{ textAlign: 'center' }}>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-menu.png" width="400" />
</Frame>
Click on "Developer" in the lefthand bar of the Settings pane, and then click on "Edit Config":
<Frame>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-developer.png" />
</Frame>
This will create a configuration file at:
* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`
if you don't already have one, and will display the file in your file system.
Open up the configuration file in any text editor. Replace the file contents with this:
<Tabs>
<Tab title="MacOS/Linux">
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop",
"/Users/username/Downloads"
]
}
}
}
```
</Tab>
<Tab title="Windows">
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"C:\\Users\\username\\Desktop",
"C:\\Users\\username\\Downloads"
]
}
}
}
```
</Tab>
</Tabs>
Make sure to replace `username` with your computer's username. The paths should point to valid directories that you want Claude to be able to access and modify. It's set up to work for Desktop and Downloads, but you can add more paths as well.
You will also need [Node.js](https://nodejs.org) on your computer for this to run properly. To verify you have Node installed, open the command line on your computer.
* On macOS, open the Terminal from your Applications folder
* On Windows, press Windows + R, type "cmd", and press Enter
Once in the command line, verify you have Node installed by entering in the following command:
```bash
node --version
```
If you get an error saying "command not found" or "node is not recognized", download Node from [nodejs.org](https://nodejs.org/).
<Tip>
**How does the configuration file work?**
This configuration file tells Claude for Desktop which MCP servers to start up every time you start the application. In this case, we have added one server called "filesystem" that will use the Node `npx` command to install and run `@modelcontextprotocol/server-filesystem`. This server, described [here](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem), will let you access your file system in Claude for Desktop.
</Tip>
<Warning>
**Command Privileges**
Claude for Desktop will run the commands in the configuration file with the permissions of your user account, and access to your local files. Only add commands if you understand and trust the source.
</Warning>
## 3. Restart Claude
After updating your configuration file, you need to restart Claude for Desktop.
Upon restarting, you should see a hammer <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon in the bottom right corner of the input box:
<Frame>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-hammer.png" />
</Frame>
After clicking on the hammer icon, you should see the tools that come with the Filesystem MCP Server:
<Frame style={{ textAlign: 'center' }}>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-tools.png" width="400" />
</Frame>
If your server isn't being picked up by Claude for Desktop, proceed to the [Troubleshooting](#troubleshooting) section for debugging tips.
## 4. Try it out!
You can now talk to Claude and ask it about your filesystem. It should know when to call the relevant tools.
Things you might try asking Claude:
* Can you write a poem and save it to my desktop?
* What are some work-related files in my downloads folder?
* Can you take all the images on my desktop and move them to a new folder called "Images"?
As needed, Claude will call the relevant tools and seek your approval before taking an action:
<Frame style={{ textAlign: 'center' }}>
<img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-approve.png" width="500" />
</Frame>
## Troubleshooting
<AccordionGroup>
<Accordion title="Server not showing up in Claude / hammer icon missing">
1. Restart Claude for Desktop completely
2. Check your `claude_desktop_config.json` file syntax
3. Make sure the file paths included in `claude_desktop_config.json` are valid and that they are absolute and not relative
4. Look at [logs](#getting-logs-from-claude-for-desktop) to see why the server is not connecting
5. In your command line, try manually running the server (replacing `username` as you did in `claude_desktop_config.json`) to see if you get any errors:
<Tabs>
<Tab title="MacOS/Linux">
```bash
npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads
```
</Tab>
<Tab title="Windows">
```bash
npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads
```
</Tab>
</Tabs>
</Accordion>
<Accordion title="Getting logs from Claude for Desktop">
Claude.app logging related to MCP is written to log files in:
* macOS: `~/Library/Logs/Claude`
* Windows: `%APPDATA%\Claude\logs`
* `mcp.log` will contain general logging about MCP connections and connection failures.
* Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server.
You can run the following command to list recent logs and follow along with any new ones (on Windows, it will only show recent logs):
<Tabs>
<Tab title="MacOS/Linux">
```bash
# Check Claude's logs for errors
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
```
</Tab>
<Tab title="Windows">
```bash
type "%APPDATA%\Claude\logs\mcp*.log"
```
</Tab>
</Tabs>
</Accordion>
<Accordion title="Tool calls failing silently">
If Claude attempts to use the tools but they fail:
1. Check Claude's logs for errors
2. Verify your server builds and runs without errors
3. Try restarting Claude for Desktop
</Accordion>
<Accordion title="None of this is working. What do I do?">
Please refer to our [debugging guide](/docs/tools/debugging) for better debugging tools and more detailed guidance.
</Accordion>
<Accordion title="ENOENT error and `${APPDATA}` in paths on Windows">
If your configured server fails to load, and you see within its logs an error referring to `${APPDATA}` within a path, you may need to add the expanded value of `%APPDATA%` to your `env` key in `claude_desktop_config.json`:
```json
{
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
"BRAVE_API_KEY": "..."
}
}
}
```
With this change in place, launch Claude Desktop once again.
<Warning>
**NPM should be installed globally**
The `npx` command may continue to fail if you have not installed NPM globally. If NPM is already installed globally, you will find `%APPDATA%\npm` exists on your system. If not, you can install NPM globally by running the following command:
```bash
npm install -g npm
```
</Warning>
</Accordion>
</AccordionGroup>
## Next steps
<CardGroup cols={2}>
<Card title="Explore other servers" icon="grid" href="/examples">
Check out our gallery of official MCP servers and implementations
</Card>
<Card title="Build your own server" icon="code" href="/quickstart/server">
Now build your own custom server to use in Claude for Desktop and other clients
</Card>
</CardGroup>
# MCP Client
Source: https://modelcontextprotocol.io/sdk/java/mcp-client
Learn how to use the Model Context Protocol (MCP) client to interact with MCP servers
# Model Context Protocol Client
The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers. It implements the client-side of the protocol, handling:
* Protocol version negotiation to ensure compatibility with servers
* Capability negotiation to determine available features
* Message transport and JSON-RPC communication
* Tool discovery and execution
* Resource access and management
* Prompt system interactions
* Optional features like roots management and sampling support
The client provides both synchronous and asynchronous APIs for flexibility in different application contexts.
<Tabs>
<Tab title="Sync API">
```java
// Create a sync client with custom configuration
McpSyncClient client = McpClient.sync(transport)
.requestTimeout(Duration.ofSeconds(10))
.capabilities(ClientCapabilities.builder()
.roots(true) // Enable roots capability
.sampling() // Enable sampling capability
.build())
.sampling(request -> new CreateMessageResult(response))
.build();
// Initialize connection
client.initialize();
// List available tools
ListToolsResult tools = client.listTools();
// Call a tool
CallToolResult result = client.callTool(
new CallToolRequest("calculator",
Map.of("operation", "add", "a", 2, "b", 3))
);
// List and read resources
ListResourcesResult resources = client.listResources();
ReadResourceResult resource = client.readResource(
new ReadResourceRequest("resource://uri")
);
// List and use prompts
ListPromptsResult prompts = client.listPrompts();
GetPromptResult prompt = client.getPrompt(
new GetPromptRequest("greeting", Map.of("name", "Spring"))
);
// Add/remove roots
client.addRoot(new Root("file:///path", "description"));
client.removeRoot("file:///path");
// Close client
client.closeGracefully();
```
</Tab>
<Tab title="Async API">
```java
// Create an async client with custom configuration
McpAsyncClient client = McpClient.async(transport)
.requestTimeout(Duration.ofSeconds(10))
.capabilities(ClientCapabilities.builder()
.roots(true) // Enable roots capability
.sampling() // Enable sampling capability
.build())
.sampling(request -> Mono.just(new CreateMessageResult(response)))
.toolsChangeConsumer(tools -> Mono.fromRunnable(() -> {
logger.info("Tools updated: {}", tools);
}))
.resourcesChangeConsumer(resources -> Mono.fromRunnable(() -> {
logger.info("Resources updated: {}", resources);
}))
.promptsChangeConsumer(prompts -> Mono.fromRunnable(() -> {
logger.info("Prompts updated: {}", prompts);
}))
.build();
// Initialize connection and use features
client.initialize()
.flatMap(initResult -> client.listTools())
.flatMap(tools -> {
return client.callTool(new CallToolRequest(
"calculator",
Map.of("operation", "add", "a", 2, "b", 3)
));
})
.flatMap(result -> {
return client.listResources()
.flatMap(resources ->
client.readResource(new ReadResourceRequest("resource://uri"))
);
})
.flatMap(resource -> {
return client.listPrompts()
.flatMap(prompts ->
client.getPrompt(new GetPromptRequest(
"greeting",
Map.of("name", "Spring")
))
);
})
.flatMap(prompt -> {
return client.addRoot(new Root("file:///path", "description"))
.then(client.removeRoot("file:///path"));
})
.doFinally(signalType -> {
client.closeGracefully().subscribe();
})
.subscribe();
```
</Tab>
</Tabs>
## Client Transport
The transport layer handles the communication between MCP clients and servers, providing different implementations for various use cases. The client transport manages message serialization, connection establishment, and protocol-specific communication patterns.
<Tabs>
<Tab title="STDIO">
Creates transport for in-process based communication
```java
ServerParameters params = ServerParameters.builder("npx")
.args("-y", "@modelcontextprotocol/server-everything", "dir")
.build();
McpTransport transport = new StdioClientTransport(params);
```
</Tab>
<Tab title="SSE (HttpClient)">
Creates a framework agnostic (pure Java API) SSE client transport. Included in the core mcp module.
```java
McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
```
</Tab>
<Tab title="SSE (WebFlux)">
Creates WebFlux-based SSE client transport. Requires the mcp-webflux-sse-transport dependency.
```java
WebClient.Builder webClientBuilder = WebClient.builder()
.baseUrl("http://your-mcp-server");
McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);
```
</Tab>
</Tabs>
## Client Capabilities
The client can be configured with various capabilities:
```java
var capabilities = ClientCapabilities.builder()
.roots(true) // Enable filesystem roots support with list changes notifications
.sampling() // Enable LLM sampling support
.build();
```
### Roots Support
Roots define the boundaries of where servers can operate within the filesystem:
```java
// Add a root dynamically
client.addRoot(new Root("file:///path", "description"));
// Remove a root
client.removeRoot("file:///path");
// Notify server of roots changes
client.rootsListChangedNotification();
```
The roots capability allows servers to:
* Request the list of accessible filesystem roots
* Receive notifications when the roots list changes
* Understand which directories and files they have access to
### Sampling Support
Sampling enables servers to request LLM interactions ("completions" or "generations") through the client:
```java
// Configure sampling handler
Function<CreateMessageRequest, CreateMessageResult> samplingHandler = request -> {
// Sampling implementation that interfaces with LLM
return new CreateMessageResult(response);
};
// Create client with sampling support
var client = McpClient.sync(transport)
.capabilities(ClientCapabilities.builder()
.sampling()
.build())
.sampling(samplingHandler)
.build();
```
This capability allows:
* Servers to leverage AI capabilities without requiring API keys
* Clients to maintain control over model access and permissions
* Support for both text and image-based interactions
* Optional inclusion of MCP server context in prompts
## Using MCP Clients
### Tool Execution
Tools are server-side functions that clients can discover and execute. The MCP client provides methods to list available tools and execute them with specific parameters. Each tool has a unique name and accepts a map of parameters.
<Tabs>
<Tab title="Sync API">
```java
// List available tools and their names
var tools = client.listTools();
tools.forEach(tool -> System.out.println(tool.getName()));
// Execute a tool with parameters
var result = client.callTool("calculator", Map.of(
"operation", "add",
"a", 1,
"b", 2
));
```
</Tab>
<Tab title="Async API">
```java
// List available tools asynchronously
client.listTools()
.doOnNext(tools -> tools.forEach(tool ->
System.out.println(tool.getName())))
.subscribe();
// Execute a tool asynchronously
client.callTool("calculator", Map.of(
"operation", "add",
"a", 1,
"b", 2
))
.subscribe();
```
</Tab>
</Tabs>
### Resource Access
Resources represent server-side data sources that clients can access using URI templates. The MCP client provides methods to discover available resources and retrieve their contents through a standardized interface.
<Tabs>
<Tab title="Sync API">
```java
// List available resources and their names
var resources = client.listResources();
resources.forEach(resource -> System.out.println(resource.getName()));
// Retrieve resource content using a URI template
var content = client.getResource("file", Map.of(
"path", "/path/to/file.txt"
));
```
</Tab>
<Tab title="Async API">
```java
// List available resources asynchronously
client.listResources()
.doOnNext(resources -> resources.forEach(resource ->
System.out.println(resource.getName())))
.subscribe();
// Retrieve resource content asynchronously
client.getResource("file", Map.of(
"path", "/path/to/file.txt"
))
.subscribe();
```
</Tab>
</Tabs>
### Prompt System
The prompt system enables interaction with server-side prompt templates. These templates can be discovered and executed with custom parameters, allowing for dynamic text generation based on predefined patterns.
<Tabs>
<Tab title="Sync API">
```java
// List available prompt templates
var prompts = client.listPrompts();
prompts.forEach(prompt -> System.out.println(prompt.getName()));
// Execute a prompt template with parameters
var response = client.executePrompt("echo", Map.of(
"text", "Hello, World!"
));
```
</Tab>
<Tab title="Async API">
```java
// List available prompt templates asynchronously
client.listPrompts()
.doOnNext(prompts -> prompts.forEach(prompt ->
System.out.println(prompt.getName())))
.subscribe();
// Execute a prompt template asynchronously
client.executePrompt("echo", Map.of(
"text", "Hello, World!"
))
.subscribe();
```
</Tab>
</Tabs>
# Overview
Source: https://modelcontextprotocol.io/sdk/java/mcp-overview
Introduction to the Model Context Protocol (MCP) Java SDK
Java SDK for the [Model Context Protocol](https://modelcontextprotocol.org/docs/concepts/architecture)
enables standardized integration between AI models and tools.
## Features
* MCP Client and MCP Server implementations supporting:
* Protocol [version compatibility negotiation](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle/#initialization)
* [Tool](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/) discovery, execution, list change notifications
* [Resource](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/) management with URI templates
* [Roots](https://spec.modelcontextprotocol.io/specification/2024-11-05/client/roots/) list management and notifications
* [Prompt](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/) handling and management
* [Sampling](https://spec.modelcontextprotocol.io/specification/2024-11-05/client/sampling/) support for AI model interactions
* Multiple transport implementations:
* Default transports:
* Stdio-based transport for process-based communication
* Java HttpClient-based SSE client transport for HTTP SSE Client-side streaming
* Servlet-based SSE server transport for HTTP SSE Server streaming
* Spring-based transports:
* WebFlux SSE client and server transports for reactive HTTP streaming
* WebMVC SSE transport for servlet-based HTTP streaming
* Supports Synchronous and Asynchronous programming paradigms
## Architecture
The SDK follows a layered architecture with clear separation of concerns:
* **Client/Server Layer (McpClient/McpServer)**: Both use McpSession for sync/async operations,
with McpClient handling client-side protocol operations and McpServer managing server-side protocol operations.
* **Session Layer (McpSession)**: Manages communication patterns and state using DefaultMcpSession implementation.
* **Transport Layer (McpTransport)**: Handles JSON-RPC message serialization/deserialization via:
* StdioTransport (stdin/stdout) in the core module
* HTTP SSE transports in dedicated transport modules (Java HttpClient, Spring WebFlux, Spring WebMVC)
The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers.
It implements the client-side of the protocol.
The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients.
It implements the server-side of the protocol.
Key Interactions:
* **Client/Server Initialization**: Transport setup, protocol compatibility check, capability negotiation, and implementation details exchange.
* **Message Flow**: JSON-RPC message handling with validation, type-safe response processing, and error handling.
* **Resource Management**: Resource discovery, URI template-based access, subscription system, and content retrieval.
## Dependencies
Add the following Maven dependency to your project:
<Tabs>
<Tab title="Maven">
The core MCP functionality:
```xml
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp</artifactId>
</dependency>
```
For HTTP SSE transport implementations, add one of the following dependencies:
```xml
<!-- Spring WebFlux-based SSE client and server transport -->
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp-spring-webflux</artifactId>
</dependency>
<!-- Spring WebMVC-based SSE server transport -->
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp-spring-webmvc</artifactId>
</dependency>
```
</Tab>
<Tab title="Gradle">
The core MCP functionality:
```groovy
dependencies {
implementation platform("io.modelcontextprotocol.sdk:mcp")
//...
}
```
For HTTP SSE transport implementations, add one of the following dependencies:
```groovy
// Spring WebFlux-based SSE client and server transport
dependencies {
implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webflux")
}
// Spring WebMVC-based SSE server transport
dependencies {
implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webmvc")
}
```
</Tab>
</Tabs>
### Bill of Materials (BOM)
The Bill of Materials (BOM) declares the recommended versions of all the dependencies used by a given release.
Using the BOM from your application's build script avoids the need for you to specify and maintain the dependency versions yourself.
Instead, the version of the BOM you're using determines the utilized dependency versions.
It also ensures that you're using supported and tested versions of the dependencies by default, unless you choose to override them.
Add the BOM to your project:
<Tabs>
<Tab title="Maven">
```xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp-bom</artifactId>
<version>0.7.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
```
</Tab>
<Tab title="Gradle">
```groovy
dependencies {
implementation platform("io.modelcontextprotocol.sdk:mcp-bom:0.7.0")
//...
}
```
Gradle users can also use the Spring AI MCP BOM by leveraging Gradle (5.0+) native support for declaring dependency constraints using a Maven BOM.
This is implemented by adding a 'platform' dependency handler method to the dependencies section of your Gradle build script.
As shown in the snippet above this can then be followed by version-less declarations of the Starter Dependencies for the one or more spring-ai modules you wish to use, e.g. spring-ai-openai.
</Tab>
</Tabs>
Replace the version number with the version of the BOM you want to use.
### Available Dependencies
The following dependencies are available and managed by the BOM:
* Core Dependencies
* `io.modelcontextprotocol.sdk:mcp` - Core MCP library providing the base functionality and APIs for Model Context Protocol implementation.
* Transport Dependencies
* `io.modelcontextprotocol.sdk:mcp-spring-webflux` - WebFlux-based Server-Sent Events (SSE) transport implementation for reactive applications.
* `io.modelcontextprotocol.sdk:mcp-spring-webmvc` - WebMVC-based Server-Sent Events (SSE) transport implementation for servlet-based applications.
* Testing Dependencies
* `io.modelcontextprotocol.sdk:mcp-test` - Testing utilities and support for MCP-based applications.
# MCP Server
Source: https://modelcontextprotocol.io/sdk/java/mcp-server
Learn how to implement and configure a Model Context Protocol (MCP) server
## Overview
The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients. It implements the server-side of the protocol, responsible for:
* Exposing tools that clients can discover and execute
* Managing resources with URI-based access patterns
* Providing prompt templates and handling prompt requests
* Supporting capability negotiation with clients
* Implementing server-side protocol operations
* Managing concurrent client connections
* Providing structured logging and notifications
The server supports both synchronous and asynchronous APIs, allowing for flexible integration in different application contexts.
<Tabs>
<Tab title="Sync API">
```java
// Create a server with custom configuration
McpSyncServer syncServer = McpServer.sync(transport)
.serverInfo("my-server", "1.0.0")
.capabilities(ServerCapabilities.builder()
.resources(true) // Enable resource support
.tools(true) // Enable tool support
.prompts(true) // Enable prompt support
.logging() // Enable logging support
.build())
.build();
// Register tools, resources, and prompts
syncServer.addTool(syncToolRegistration);
syncServer.addResource(syncResourceRegistration);
syncServer.addPrompt(syncPromptRegistration);
// Send logging notifications
syncServer.loggingNotification(LoggingMessageNotification.builder()
.level(LoggingLevel.INFO)
.logger("custom-logger")
.data("Server initialized")
.build());
// Close the server when done
syncServer.close();
```
</Tab>
<Tab title="Async API">
```java
// Create an async server with custom configuration
McpAsyncServer asyncServer = McpServer.async(transport)
.serverInfo("my-server", "1.0.0")
.capabilities(ServerCapabilities.builder()
.resources(true) // Enable resource support
.tools(true) // Enable tool support
.prompts(true) // Enable prompt support
.logging() // Enable logging support
.build())
.build();
// Register tools, resources, and prompts
asyncServer.addTool(asyncToolRegistration)
.doOnSuccess(v -> logger.info("Tool registered"))
.subscribe();
asyncServer.addResource(asyncResourceRegistration)
.doOnSuccess(v -> logger.info("Resource registered"))
.subscribe();
asyncServer.addPrompt(asyncPromptRegistration)
.doOnSuccess(v -> logger.info("Prompt registered"))
.subscribe();
// Send logging notifications
asyncServer.loggingNotification(LoggingMessageNotification.builder()
.level(LoggingLevel.INFO)
.logger("custom-logger")
.data("Server initialized")
.build());
// Close the server when done
asyncServer.close()
.doOnSuccess(v -> logger.info("Server closed"))
.subscribe();
```
</Tab>
</Tabs>
## Server Transport
The transport layer in the MCP SDK is responsible for handling the communication between clients and servers. It provides different implementations to support various communication protocols and patterns. The SDK includes several built-in transport implementations:
<Tabs>
<Tab title="STDIO">
<>
Create in-process based transport:
```java
StdioServerTransport transport = new StdioServerTransport(new ObjectMapper());
```
Provides bidirectional JSON-RPC message handling over standard input/output streams with non-blocking message processing, serialization/deserialization, and graceful shutdown support.
Key features:
<ul>
<li>Bidirectional communication through stdin/stdout</li>
<li>Process-based integration support</li>
<li>Simple setup and configuration</li>
<li>Lightweight implementation</li>
</ul>
</>
</Tab>
<Tab title="SSE (WebFlux)">
<>
<p>Creates WebFlux-based SSE server transport.<br />Requires the <code>mcp-spring-webflux</code> dependency.</p>
```java
@Configuration
class McpConfig {
@Bean
WebFluxSseServerTransport webFluxSseServerTransport(ObjectMapper mapper) {
return new WebFluxSseServerTransport(mapper, "/mcp/message");
}
@Bean
RouterFunction<?> mcpRouterFunction(WebFluxSseServerTransport transport) {
return transport.getRouterFunction();
}
}
```
<p>Implements the MCP HTTP with SSE transport specification, providing:</p>
<ul>
<li>Reactive HTTP streaming with WebFlux</li>
<li>Concurrent client connections through SSE endpoints</li>
<li>Message routing and session management</li>
<li>Graceful shutdown capabilities</li>
</ul>
</>
</Tab>
<Tab title="SSE (WebMvc)">
<>
<p>Creates WebMvc-based SSE server transport.<br />Requires the <code>mcp-spring-webmvc</code> dependency.</p>
```java
@Configuration
@EnableWebMvc
class McpConfig {
@Bean
WebMvcSseServerTransport webMvcSseServerTransport(ObjectMapper mapper) {
return new WebMvcSseServerTransport(mapper, "/mcp/message");
}
@Bean
RouterFunction<ServerResponse> mcpRouterFunction(WebMvcSseServerTransport transport) {
return transport.getRouterFunction();
}
}
```
<p>Implements the MCP HTTP with SSE transport specification, providing:</p>
<ul>
<li>Server-side event streaming</li>
<li>Integration with Spring WebMVC</li>
<li>Support for traditional web applications</li>
<li>Synchronous operation handling</li>
</ul>
</>
</Tab>
<Tab title="SSE (Servlet)">
<>
<p>
Creates a Servlet-based SSE server transport. It is included in the core <code>mcp</code> module.<br />
The <code>HttpServletSseServerTransport</code> can be used with any Servlet container.<br />
To use it with a Spring Web application, you can register it as a Servlet bean:
</p>
```java
@Configuration
@EnableWebMvc
public class McpServerConfig implements WebMvcConfigurer {
@Bean
public HttpServletSseServerTransport servletSseServerTransport() {
return new HttpServletSseServerTransport(new ObjectMapper(), "/mcp/message");
}
@Bean
public ServletRegistrationBean customServletBean(HttpServletSseServerTransport servlet) {
return new ServletRegistrationBean(servlet);
}
}
```
<p>
Implements the MCP HTTP with SSE transport specification using the traditional Servlet API, providing:
</p>
<ul>
<li>Asynchronous message handling using Servlet 6.0 async support</li>
<li>Session management for multiple client connections</li>
<li>
Two types of endpoints:
<ul>
<li>SSE endpoint (<code>/sse</code>) for server-to-client events</li>
<li>Message endpoint (configurable) for client-to-server requests</li>
</ul>
</li>
<li>Error handling and response formatting</li>
<li>Graceful shutdown support</li>
</ul>
</>
</Tab>
</Tabs>
## Server Capabilities
The server can be configured with various capabilities:
```java
var capabilities = ServerCapabilities.builder()
.resources(false, true) // Resource support with list changes notifications
.tools(true) // Tool support with list changes notifications
.prompts(true) // Prompt support with list changes notifications
.logging() // Enable logging support (enabled by default with loging level INFO)
.build();
```
### Logging Support
The server provides structured logging capabilities that allow sending log messages to clients with different severity levels:
```java
// Send a log message to clients
server.loggingNotification(LoggingMessageNotification.builder()
.level(LoggingLevel.INFO)
.logger("custom-logger")
.data("Custom log message")
.build());
```
Clients can control the minimum logging level they receive through the `mcpClient.setLoggingLevel(level)` request. Messages below the set level will be filtered out.
Supported logging levels (in order of increasing severity): DEBUG (0), INFO (1), NOTICE (2), WARNING (3), ERROR (4), CRITICAL (5), ALERT (6), EMERGENCY (7)
### Tool Registration
<Tabs>
<Tab title="Sync">
```java
// Sync tool registration
var schema = """
{
"type" : "object",
"id" : "urn:jsonschema:Operation",
"properties" : {
"operation" : {
"type" : "string"
},
"a" : {
"type" : "number"
},
"b" : {
"type" : "number"
}
}
}
""";
var syncToolRegistration = new McpServerFeatures.SyncToolRegistration(
new Tool("calculator", "Basic calculator", schema),
arguments -> {
// Tool implementation
return new CallToolResult(result, false);
}
);
```
</Tab>
<Tab title="Async">
```java
// Async tool registration
var schema = """
{
"type" : "object",
"id" : "urn:jsonschema:Operation",
"properties" : {
"operation" : {
"type" : "string"
},
"a" : {
"type" : "number"
},
"b" : {
"type" : "number"
}
}
}
""";
var asyncToolRegistration = new McpServerFeatures.AsyncToolRegistration(
new Tool("calculator", "Basic calculator", schema),
arguments -> {
// Tool implementation
return Mono.just(new CallToolResult(result, false));
}
);
```
</Tab>
</Tabs>
### Resource Registration
<Tabs>
<Tab title="Sync">
```java
// Sync resource registration
var syncResourceRegistration = new McpServerFeatures.SyncResourceRegistration(
new Resource("custom://resource", "name", "description", "mime-type", null),
request -> {
// Resource read implementation
return new ReadResourceResult(contents);
}
);
```
</Tab>
<Tab title="Async">
```java
// Async resource registration
var asyncResourceRegistration = new McpServerFeatures.AsyncResourceRegistration(
new Resource("custom://resource", "name", "description", "mime-type", null),
request -> {
// Resource read implementation
return Mono.just(new ReadResourceResult(contents));
}
);
```
</Tab>
</Tabs>
### Prompt Registration
<Tabs>
<Tab title="Sync">
```java
// Sync prompt registration
var syncPromptRegistration = new McpServerFeatures.SyncPromptRegistration(
new Prompt("greeting", "description", List.of(
new PromptArgument("name", "description", true)
)),
request -> {
// Prompt implementation
return new GetPromptResult(description, messages);
}
);
```
</Tab>
<Tab title="Async">
```java
// Async prompt registration
var asyncPromptRegistration = new McpServerFeatures.AsyncPromptRegistration(
new Prompt("greeting", "description", List.of(
new PromptArgument("name", "description", true)
)),
request -> {
// Prompt implementation
return Mono.just(new GetPromptResult(description, messages));
}
);
```
</Tab>
</Tabs>
## Error Handling
The SDK provides comprehensive error handling through the McpError class, covering protocol compatibility, transport communication, JSON-RPC messaging, tool execution, resource management, prompt handling, timeouts, and connection issues. This unified error handling approach ensures consistent and reliable error management across both synchronous and asynchronous operations.
# Building MCP with LLMs
Source: https://modelcontextprotocol.io/tutorials/building-mcp-with-llms
Speed up your MCP development using LLMs such as Claude!
This guide will help you use LLMs to help you build custom Model Context Protocol (MCP) servers and clients. We'll be focusing on Claude for this tutorial, but you can do this with any frontier LLM.
## Preparing the documentation
Before starting, gather the necessary documentation to help Claude understand MCP:
1. Visit [https://modelcontextprotocol.io/llms-full.txt](https://modelcontextprotocol.io/llms-full.txt) and copy the full documentation text
2. Navigate to either the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) or [Python SDK repository](https://github.com/modelcontextprotocol/python-sdk)
3. Copy the README files and other relevant documentation
4. Paste these documents into your conversation with Claude
## Describing your server
Once you've provided the documentation, clearly describe to Claude what kind of server you want to build. Be specific about:
* What resources your server will expose
* What tools it will provide
* Any prompts it should offer
* What external systems it needs to interact with
For example:
```
Build an MCP server that:
- Connects to my company's PostgreSQL database
- Exposes table schemas as resources
- Provides tools for running read-only SQL queries
- Includes prompts for common data analysis tasks
```
## Working with Claude
When working with Claude on MCP servers:
1. Start with the core functionality first, then iterate to add more features
2. Ask Claude to explain any parts of the code you don't understand
3. Request modifications or improvements as needed
4. Have Claude help you test the server and handle edge cases
Claude can help implement all the key MCP features:
* Resource management and exposure
* Tool definitions and implementations
* Prompt templates and handlers
* Error handling and logging
* Connection and transport setup
## Best practices
When building MCP servers with Claude:
* Break down complex servers into smaller pieces
* Test each component thoroughly before moving on
* Keep security in mind - validate inputs and limit access appropriately
* Document your code well for future maintenance
* Follow MCP protocol specifications carefully
## Next steps
After Claude helps you build your server:
1. Review the generated code carefully
2. Test the server with the MCP Inspector tool
3. Connect it to Claude.app or other MCP clients
4. Iterate based on real usage and feedback
Remember that Claude can help you modify and improve your server as requirements change over time.
Need more guidance? Just ask Claude specific questions about implementing MCP features or troubleshooting issues that arise.
================
File: MCP-Typescript-readme.txt
================
MCP TypeScript SDK NPM Version MIT licensed
Table of Contents
Overview
Installation
Quickstart
What is MCP?
Core Concepts
Server
Resources
Tools
Prompts
Running Your Server
stdio
HTTP with SSE
Testing and Debugging
Examples
Echo Server
SQLite Explorer
Advanced Usage
Low-Level Server
Writing MCP Clients
Server Capabilities
Overview
The Model Context Protocol allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. This TypeScript SDK implements the full MCP specification, making it easy to:
Build MCP clients that can connect to any MCP server
Create MCP servers that expose resources, prompts and tools
Use standard transports like stdio and SSE
Handle all MCP protocol messages and lifecycle events
Installation
npm install @modelcontextprotocol/sdk
Quick Start
Let's create a simple MCP server that exposes a calculator tool and some data:
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
// Create an MCP server
const server = new McpServer({
name: "Demo",
version: "1.0.0"
});
// Add an addition tool
server.tool("add",
{ a: z.number(), b: z.number() },
async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }]
})
);
// Add a dynamic greeting resource
server.resource(
"greeting",
new ResourceTemplate("greeting://{name}", { list: undefined }),
async (uri, { name }) => ({
contents: [{
uri: uri.href,
text: `Hello, ${name}!`
}]
})
);
// Start receiving messages on stdin and sending messages on stdout
const transport = new StdioServerTransport();
await server.connect(transport);
What is MCP?
The Model Context Protocol (MCP) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can:
Expose data through Resources (think of these sort of like GET endpoints; they are used to load information into the LLM's context)
Provide functionality through Tools (sort of like POST endpoints; they are used to execute code or otherwise produce a side effect)
Define interaction patterns through Prompts (reusable templates for LLM interactions)
And more!
Core Concepts
Server
The McpServer is your core interface to the MCP protocol. It handles connection management, protocol compliance, and message routing:
const server = new McpServer({
name: "My App",
version: "1.0.0"
});
Resources
Resources are how you expose data to LLMs. They're similar to GET endpoints in a REST API - they provide data but shouldn't perform significant computation or have side effects:
// Static resource
server.resource(
"config",
"config://app",
async (uri) => ({
contents: [{
uri: uri.href,
text: "App configuration here"
}]
})
);
// Dynamic resource with parameters
server.resource(
"user-profile",
new ResourceTemplate("users://{userId}/profile", { list: undefined }),
async (uri, { userId }) => ({
contents: [{
uri: uri.href,
text: `Profile data for user ${userId}`
}]
})
);
Tools
Tools let LLMs take actions through your server. Unlike resources, tools are expected to perform computation and have side effects:
// Simple tool with parameters
server.tool(
"calculate-bmi",
{
weightKg: z.number(),
heightM: z.number()
},
async ({ weightKg, heightM }) => ({
content: [{
type: "text",
text: String(weightKg / (heightM * heightM))
}]
})
);
// Async tool with external API call
server.tool(
"fetch-weather",
{ city: z.string() },
async ({ city }) => {
const response = await fetch(`https://api.weather.com/${city}`);
const data = await response.text();
return {
content: [{ type: "text", text: data }]
};
}
);
Prompts
Prompts are reusable templates that help LLMs interact with your server effectively:
server.prompt(
"review-code",
{ code: z.string() },
({ code }) => ({
messages: [{
role: "user",
content: {
type: "text",
text: `Please review this code:\n\n${code}`
}
}]
})
);
Running Your Server
MCP servers in TypeScript need to be connected to a transport to communicate with clients. How you start the server depends on the choice of transport:
stdio
For command-line tools and direct integrations:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = new McpServer({
name: "example-server",
version: "1.0.0"
});
// ... set up server resources, tools, and prompts ...
const transport = new StdioServerTransport();
await server.connect(transport);
HTTP with SSE
For remote servers, start a web server with a Server-Sent Events (SSE) endpoint, and a separate endpoint for the client to send its messages to:
import express from "express";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
const server = new McpServer({
name: "example-server",
version: "1.0.0"
});
// ... set up server resources, tools, and prompts ...
const app = express();
app.get("/sse", async (req, res) => {
const transport = new SSEServerTransport("/messages", res);
await server.connect(transport);
});
app.post("/messages", async (req, res) => {
// Note: to support multiple simultaneous connections, these messages will
// need to be routed to a specific matching transport. (This logic isn't
// implemented here, for simplicity.)
await transport.handlePostMessage(req, res);
});
app.listen(3001);
Testing and Debugging
To test your server, you can use the MCP Inspector. See its README for more information.
Examples
Echo Server
A simple server demonstrating resources, tools, and prompts:
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
const server = new McpServer({
name: "Echo",
version: "1.0.0"
});
server.resource(
"echo",
new ResourceTemplate("echo://{message}", { list: undefined }),
async (uri, { message }) => ({
contents: [{
uri: uri.href,
text: `Resource echo: ${message}`
}]
})
);
server.tool(
"echo",
{ message: z.string() },
async ({ message }) => ({
content: [{ type: "text", text: `Tool echo: ${message}` }]
})
);
server.prompt(
"echo",
{ message: z.string() },
({ message }) => ({
messages: [{
role: "user",
content: {
type: "text",
text: `Please process this message: ${message}`
}
}]
})
);
SQLite Explorer
A more complex example showing database integration:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import sqlite3 from "sqlite3";
import { promisify } from "util";
import { z } from "zod";
const server = new McpServer({
name: "SQLite Explorer",
version: "1.0.0"
});
// Helper to create DB connection
const getDb = () => {
const db = new sqlite3.Database("database.db");
return {
all: promisify<string, any[]>(db.all.bind(db)),
close: promisify(db.close.bind(db))
};
};
server.resource(
"schema",
"schema://main",
async (uri) => {
const db = getDb();
try {
const tables = await db.all(
"SELECT sql FROM sqlite_master WHERE type='table'"
);
return {
contents: [{
uri: uri.href,
text: tables.map((t: {sql: string}) => t.sql).join("\n")
}]
};
} finally {
await db.close();
}
}
);
server.tool(
"query",
{ sql: z.string() },
async ({ sql }) => {
const db = getDb();
try {
const results = await db.all(sql);
return {
content: [{
type: "text",
text: JSON.stringify(results, null, 2)
}]
};
} catch (err: unknown) {
const error = err as Error;
return {
content: [{
type: "text",
text: `Error: ${error.message}`
}],
isError: true
};
} finally {
await db.close();
}
}
);
Advanced Usage
Low-Level Server
For more control, you can use the low-level Server class directly:
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
ListPromptsRequestSchema,
GetPromptRequestSchema
} from "@modelcontextprotocol/sdk/types.js";
const server = new Server(
{
name: "example-server",
version: "1.0.0"
},
{
capabilities: {
prompts: {}
}
}
);
server.setRequestHandler(ListPromptsRequestSchema, async () => {
return {
prompts: [{
name: "example-prompt",
description: "An example prompt template",
arguments: [{
name: "arg1",
description: "Example argument",
required: true
}]
}]
};
});
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
if (request.params.name !== "example-prompt") {
throw new Error("Unknown prompt");
}
return {
description: "Example prompt",
messages: [{
role: "user",
content: {
type: "text",
text: "Example prompt text"
}
}]
};
});
const transport = new StdioServerTransport();
await server.connect(transport);
Writing MCP Clients
The SDK provides a high-level client interface:
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const transport = new StdioClientTransport({
command: "node",
args: ["server.js"]
});
const client = new Client(
{
name: "example-client",
version: "1.0.0"
},
{
capabilities: {
prompts: {},
resources: {},
tools: {}
}
}
);
await client.connect(transport);
// List prompts
const prompts = await client.listPrompts();
// Get a prompt
const prompt = await client.getPrompt("example-prompt", {
arg1: "value"
});
// List resources
const resources = await client.listResources();
// Read a resource
const resource = await client.readResource("file:///example.txt");
// Call a tool
const result = await client.callTool({
name: "example-tool",
arguments: {
arg1: "value"
}
});
================
File: package.json
================
{
"name": "vibe-coder-mcp",
"version": "0.3.0",
"description": "A custom MCP for vibecoding",
"private": true,
"type": "module",
"bin": {
"vibe-coder-mcp": "./build/mcp-server.js"
},
"files": [
"build"
],
"scripts": {
"build": "tsc --project tsconfig.build.json && node -e \"require('fs').chmodSync('build/mcp-server.js', '755')\"",
"watch": "tsc --project tsconfig.build.json --watch",
"inspector": "npx @modelcontextprotocol/inspector build/mcp-server.js"
},
"dependencies": {
"@modelcontextprotocol/sdk": "1.7.0",
"zod": "^3.22.4"
},
"devDependencies": {
"@types/node": "^20.11.24",
"typescript": "^5.3.3"
}
}
================
File: README.md
================
# Vibe-Coder MCP Server
A Model Context Protocol server that implements a structured development workflow for LLM-based coding.
## Overview
This MCP server helps LLMs build features in an organized, clean, and safe manner by providing:
- A structured feature clarification process with guided questions
- PRD and implementation plan generation
- Phased development with task tracking
- Progress tracking and status reporting
## Features
### Resources
- Feature details, PRDs, and implementation plans
- Progress reports and status tracking
- Phase and task details
### Tools
- `start_feature_clarification` - Begin the feature clarification process
- `provide_clarification` - Answer clarification questions about a feature
- `generate_prd` - Generate a Product Requirements Document and implementation plan
- `create_phase` - Create a development phase for a feature
- `add_task` - Add tasks to a development phase
- `update_phase_status` - Update the status of a phase
- `update_task_status` - Update the completion status of a task
- `get_next_phase_action` - Get guidance on what to do next
### Prompts
- `feature-planning` - A prompt template for planning feature development
## Development
Install dependencies:
```bash
npm install
```
Build the server:
```bash
npm run build
```
For development with auto-rebuild:
```bash
npm run watch
```
## Installation
To use with compatible MCP clients:
On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"vibe-coder-mcp": {
"command": "/path/to/vibe-coder-mcp/build/mcp-server.js"
}
}
}
```
### Debugging
Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:
```bash
npm run inspector
```
The Inspector will provide a URL to access debugging tools in your browser.
## Implementation Notes
This server is implemented using the high-level `McpServer` class from the Model Context Protocol TypeScript SDK, which simplifies the process of creating MCP servers by providing a clean API for defining resources, tools, and prompts.
```typescript
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
// Create an MCP server
const server = new McpServer({
name: "Vibe-Coder",
version: "0.3.0"
});
// Add a resource
server.resource(
"features-list",
"features://list",
async (uri) => ({ /* ... */ })
);
// Add a tool
server.tool(
"start_feature_clarification",
{ /* parameters schema */ },
async (params) => ({ /* ... */ })
);
// Add a prompt
server.prompt(
"feature-planning",
{ /* parameters schema */ },
(params) => ({ /* ... */ })
);
// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);
```
## Workflow
The Vibe-Coder MCP server is designed to guide the development process through the following steps:
1. **Feature Clarification**: Start by gathering requirements and understanding the feature's purpose, target users, and constraints
2. **Documentation**: Generate a PRD and implementation plan based on the clarified requirements
3. **Phased Development**: Break down the implementation into logical phases with clear tasks
4. **Progress Tracking**: Monitor the completion of tasks and phases to guide development
5. **Completion**: Verify that all requirements have been implemented and the feature is ready for use
================
File: test-mcp.js
================
#!/usr/bin/env node
import { spawn } from 'child_process';
import { createInterface } from 'readline';
console.log('Starting Vibe-Coder MCP server...');
// Start the MCP server
const serverProcess = spawn('node', ['./build/index.js']);
// Create readline interface to read server output
const rl = createInterface({
input: serverProcess.stdout,
output: process.stdout,
terminal: false
});
// Set up error handling
serverProcess.stderr.on('data', (data) => {
console.error(`Server stderr: ${data.toString()}`);
});
// Wait for server to start
setTimeout(() => {
console.log('Sending initialize request...');
// First, send the initialize request
const initializeMsg = {
jsonrpc: "2.0",
id: "init1",
method: "initialize",
params: {
client: {
name: "Test Client",
version: "1.0.0"
},
capabilities: {
resources: {},
tools: {},
prompts: {}
}
}
};
serverProcess.stdin.write(JSON.stringify(initializeMsg) + '\n');
// Wait for response and send clarification
let featureId = null;
let questionIndex = 0;
rl.on('line', (line) => {
try {
console.log('Raw server output:', line);
const response = JSON.parse(line);
console.log('Parsed response:', JSON.stringify(response, null, 2));
// After initialization, list available tools
if (response.id === "init1") {
console.log('Initialization successful, listing tools...');
const listToolsMsg = {
jsonrpc: "2.0",
id: "list1",
method: "listTools",
params: {}
};
serverProcess.stdin.write(JSON.stringify(listToolsMsg) + '\n');
}
// After listing tools, call the start_feature_clarification tool
if (response.id === "list1") {
console.log('Tools listed, starting feature clarification...');
const callToolMsg = {
jsonrpc: "2.0",
id: "call1",
method: "callTool",
params: {
name: "start_feature_clarification",
arguments: {
featureName: "Test Automated Feature",
initialDescription: "This is a test automated feature for testing the clarification flow"
}
}
};
serverProcess.stdin.write(JSON.stringify(callToolMsg) + '\n');
}
// Check if this is a response to start_feature_clarification
if (response.id === "call1" && response.result?.content) {
// Extract feature ID from response text
const text = response.result.content[0].text;
const match = text.match(/Feature ID: ([a-z0-9]+)/);
if (match && match[1]) {
featureId = match[1];
console.log(`Extracted feature ID: ${featureId}`);
// Send first clarification
sendClarification(featureId, questionIndex, "This is an answer to question 0");
}
}
// Check if this is a response to any of the clarification messages
if (response.id && response.id.startsWith("clarify") && response.result?.content) {
const text = response.result.content[0].text;
console.log('Clarification response text:', text);
// Check if we need to send the next question
if (text.startsWith("Response recorded.")) {
questionIndex++;
if (questionIndex < 7) { // We have 7 default questions
setTimeout(() => {
sendClarification(featureId, questionIndex, `This is an answer to question ${questionIndex}`);
}, 500);
} else {
console.log('All questions answered, test complete');
serverProcess.kill();
process.exit(0);
}
}
}
} catch (e) {
console.error('Error parsing JSON response:', e);
}
});
function sendClarification(featureId, index, answer) {
const clarifyMsg = {
jsonrpc: "2.0",
id: `clarify${index}`,
method: "callTool",
params: {
name: "provide_clarification",
arguments: {
featureId: featureId,
question: `Question #${index}`,
answer: answer
}
}
};
console.log(`Sending clarification ${index}...`);
serverProcess.stdin.write(JSON.stringify(clarifyMsg) + '\n');
}
}, 1000);
// Handle process exit
process.on('exit', () => {
serverProcess.kill();
});
================
File: tsconfig.build.json
================
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/mcp-server.ts", "src/types.ts", "src/storage.ts", "src/utils.ts", "src/clarification.ts", "src/documentation.ts"],
"exclude": ["node_modules", "src/registry.ts", "src/resource-handlers.ts", "src/tool-handlers.ts", "src/index.ts", "src/index-updated.ts"]
}
================
File: tsconfig.json
================
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}