From 3fbb9a18372f2b6a675dd6c039ba52be76f3eeb4 Mon Sep 17 00:00:00 2001 From: TheSiahxyz <164138827+TheSiahxyz@users.noreply.github.com> Date: Fri, 16 Jan 2026 08:30:14 +0900 Subject: updates --- mcp-servers/simple-mcp-server/README.md | 406 ++++++++++++++++++++++++++++++++ 1 file changed, 406 insertions(+) create mode 100644 mcp-servers/simple-mcp-server/README.md (limited to 'mcp-servers/simple-mcp-server/README.md') diff --git a/mcp-servers/simple-mcp-server/README.md b/mcp-servers/simple-mcp-server/README.md new file mode 100644 index 0000000..ad65358 --- /dev/null +++ b/mcp-servers/simple-mcp-server/README.md @@ -0,0 +1,406 @@ +# Simple MCP Server Claude Code Configuration ๐Ÿš€ + +A clean, focused Claude Code configuration for building standard MCP (Model Context Protocol) servers. Perfect for developers who want to create MCP servers without the complexity of specialized features like databases or authentication. + +## โœจ Features + +This configuration provides comprehensive support for: + +- **MCP Protocol Implementation** - Complete server setup with tools, resources, and prompts +- **Type-Safe Development** - TypeScript with Zod validation +- **Multiple Transport Options** - stdio, HTTP+SSE, WebSocket +- **Testing & Debugging** - Integration with MCP Inspector +- **Production Ready** - Docker support, logging, error handling + +## ๐Ÿ“ฆ Installation + +1. Copy the configuration to your MCP server project: + +```bash +cp -r simple-mcp-server/.claude your-mcp-project/ +cp simple-mcp-server/CLAUDE.md your-mcp-project/ + +# Make hook scripts executable +chmod +x your-mcp-project/.claude/hooks/*.sh +``` + +2. The configuration will be automatically loaded when you start Claude Code. + +## ๐Ÿค– Specialized Agents (6 total) + +### Core MCP Development + +| Agent | Description | Use Cases | +|-------|-------------|-----------| +| `mcp-architect` | MCP server architecture expert | Server structure, capability design, protocol patterns | +| `tool-builder` | Tool implementation specialist | Creating tools, parameter schemas, response formats | +| `resource-manager` | Resource system expert | URI schemes, content types, dynamic resources | + +### Development & Operations + +| Agent | Description | Use Cases | +|-------|-------------|-----------| +| `error-handler` | Error handling and debugging | Error codes, validation, troubleshooting | +| `test-writer` | Testing strategy expert | Unit tests, integration tests, MCP Inspector | +| `deployment-expert` | Deployment and packaging | Docker, npm publishing, Claude integration | + +## ๐Ÿ› ๏ธ Commands (7 total) + +### Setup & Initialization + +```bash +/init basic # Basic MCP server with one tool +/init standard # Standard server with tools and resources +/init full # Complete server with all capabilities +``` + +### Development Workflow + +```bash +/add-tool # Add a new tool to the server +/add-resource # Add a new resource endpoint +/add-prompt # Add a new prompt template +``` + +### Testing & Deployment + +```bash +/test # Run tests and validate protocol compliance +/debug # Debug server issues with detailed logging +/build # Build and prepare for deployment +/deploy # Deploy to npm or Docker registry +``` + +## ๐Ÿช Automation Hooks + +### Development Hook (`dev-watch.sh`) + +Automatically triggered on TypeScript file changes: + +- โœ… Type checking with `tsc --noEmit` +- ๐ŸŽจ Prettier formatting +- ๐Ÿ” ESLint linting +- ๐Ÿงช Test execution for changed files +- ๐Ÿ“ Update tool/resource counts + +### Build Hook (`pre-build.sh`) + +Runs before building: + +- ๐Ÿ” Lint check +- โœ… Type validation +- ๐Ÿงช Test suite execution +- ๐Ÿ“ฆ Dependency audit +- ๐Ÿท๏ธ Version validation + +### Test Hook (`test-runner.sh`) + +Enhances test execution: + +- ๐Ÿงช Run appropriate test suite +- ๐Ÿ“Š Coverage reporting +- ๐Ÿ” MCP protocol validation +- ๐Ÿ“ Test results summary + +## โš™๏ธ Configuration Details + +### Security Permissions + +```json +{ + "permissions": { + "allow": [ + "Read", "Write", "Edit", "MultiEdit", + "Grep", "Glob", "LS", + "Bash(npm run:*)", + "Bash(npx @modelcontextprotocol/inspector)", + "Bash(node dist/*.js)", + "Bash(tsx src/*.ts)" + ], + "deny": [ + "Bash(rm -rf)", + "Bash(sudo:*)", + "Read(**/*secret*)", + "Write(**/*secret*)" + ] + } +} +``` + +### Environment Variables + +Pre-configured for MCP development: + +- `NODE_ENV` - Environment mode +- `LOG_LEVEL` - Logging verbosity +- `MCP_SERVER_NAME` - Server identifier +- `MCP_SERVER_VERSION` - Server version +- `DEBUG` - Debug mode flag + +## ๐Ÿš€ Usage Examples + +### Creating a Basic MCP Server + +```bash +# 1. Initialize the project +> /init standard + +# 2. Add a custom tool +> /add-tool calculate "Performs calculations" + +# 3. Add a resource +> /add-resource config "Server configuration" + +# 4. Test the implementation +> /test + +# 5. Build for production +> /build +``` + +### Quick Server Setup + +```typescript +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; + +const server = new Server({ + name: 'my-server', + version: '1.0.0', +}, { + capabilities: { + tools: {}, + resources: {}, + }, +}); + +// Add your tools +server.addTool({ + name: 'hello', + description: 'Say hello', + inputSchema: { + type: 'object', + properties: { + name: { type: 'string' }, + }, + }, + handler: async (args) => ({ + content: [{ + type: 'text', + text: `Hello, ${args.name}!`, + }], + }), +}); + +// Connect transport +const transport = new StdioServerTransport(); +await server.connect(transport); +``` + +### Testing with MCP Inspector + +```bash +# Launch the MCP Inspector +> npx @modelcontextprotocol/inspector + +# The inspector will: +# - Connect to your server +# - Display available tools/resources +# - Allow interactive testing +# - Show protocol messages +``` + +## ๐Ÿ“Š Technology Stack + +Optimized for: + +- **TypeScript** - Type-safe development +- **Node.js** - JavaScript runtime +- **@modelcontextprotocol/sdk** - Official MCP SDK +- **Zod** - Runtime validation +- **Vitest** - Fast unit testing +- **Docker** - Containerization + +## ๐ŸŽฏ Key Features + +### MCP Protocol Support + +- Tools, Resources, and Prompts +- Multiple transport options +- Progress notifications +- Error handling with proper codes + +### Developer Experience + +- Type-safe with TypeScript +- Automatic validation with Zod +- Hot reload in development +- Comprehensive testing + +### Production Ready + +- Docker containerization +- Structured logging +- Error monitoring +- Rate limiting support + +## ๐Ÿ”ง Customization + +Edit `.claude/settings.json` to customize: + +- Tool and resource definitions +- Environment variables +- Hook configurations +- Permission settings + +## ๐Ÿ“ Best Practices + +This configuration enforces: + +1. **Protocol Compliance** - Strict MCP specification adherence +2. **Type Safety** - Full TypeScript with runtime validation +3. **Error Handling** - Proper error codes and messages +4. **Testing** - Comprehensive test coverage +5. **Documentation** - Clear code comments and API docs +6. **Security** - Input validation and sanitization + +## ๐Ÿ› Troubleshooting + +### Common Issues + +**Server not starting:** + +```bash +# Check TypeScript compilation +npm run typecheck + +# Check for missing dependencies +npm install + +# Verify Node.js version +node --version # Should be >= 18 +``` + +**Tools not appearing:** + +```bash +# Validate tool registration +/debug + +# Check MCP Inspector +npx @modelcontextprotocol/inspector +``` + +**Transport issues:** + +```bash +# Test with stdio transport first +node dist/index.js + +# For HTTP transport, check port +lsof -i :3000 +``` + +## ๐ŸŒŸ Example Projects + +### Weather Tool Server + +```typescript +server.addTool({ + name: 'get_weather', + description: 'Get weather for a location', + inputSchema: { + type: 'object', + properties: { + location: { type: 'string' }, + }, + required: ['location'], + }, + handler: async ({ location }) => { + const weather = await fetchWeather(location); + return { + content: [{ + type: 'text', + text: `Weather in ${location}: ${weather}`, + }], + }; + }, +}); +``` + +### File System Resource Server + +```typescript +server.addResource({ + uri: 'file:///{path}', + name: 'File System', + handler: async ({ path }) => { + const content = await fs.readFile(path, 'utf-8'); + return { + contents: [{ + uri: `file:///${path}`, + mimeType: 'text/plain', + text: content, + }], + }; + }, +}); +``` + +## ๐Ÿ“š Resources + +- [MCP Specification](https://spec.modelcontextprotocol.io) +- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk) +- [MCP Inspector](https://github.com/modelcontextprotocol/inspector) +- [Example MCP Servers](https://github.com/modelcontextprotocol/servers) +- [Claude Code MCP Guide](https://docs.anthropic.com/claude-code/mcp) + +## ๐ŸŽ‰ Quick Start + +```bash +# 1. Create a new MCP server project +mkdir my-mcp-server && cd my-mcp-server +npm init -y + +# 2. Install dependencies +npm install @modelcontextprotocol/sdk zod +npm install -D typescript tsx @types/node vitest + +# 3. Copy this configuration +cp -r path/to/simple-mcp-server/.claude . +cp path/to/simple-mcp-server/CLAUDE.md . + +# 4. Initialize TypeScript +npx tsc --init + +# 5. Create your server +touch src/index.ts + +# 6. Start development +npm run dev +``` + +## ๐ŸŽฏ What Makes This Configuration Special + +### Focused on Fundamentals + +- **No complexity** - Just pure MCP server development +- **No dependencies** - No databases, no authentication, no external services +- **Clean architecture** - Clear separation of concerns +- **Best practices** - Industry-standard patterns and conventions + +### Perfect For + +- Building your first MCP server +- Creating utility servers for Claude Code +- Learning MCP protocol implementation +- Prototyping new MCP capabilities +- Building production-ready MCP servers + +--- + +**Built for clean, simple MCP server development** ๐Ÿš€ + +*Create robust MCP servers with best practices and minimal complexity.* + +**Configuration Version:** 1.0.0 | **Compatible with:** @modelcontextprotocol/sdk >=1.0.0 -- cgit v1.2.3