MCP Typescript Server

MCP TypeScript服务器

 ](https://hub.docker.com/r/ajeetraina/mcp-typescript-server)  

一个从头开始使用TypeScript构建的生产就绪模型上下文协议（MCP）服务器。此实现为构建具有工具集成、资源管理和全面错误处理的AI驱动应用程序提供了一个强大、可扩展的基础。

🚀 快速开始

🐳 Docker（推荐-无需安装）

# Clone and start immediately
git clone https://github.com/ajeetraina/mcp-typescript-server.git
cd mcp-typescript-server

# Fix any Docker issues automatically
chmod +x scripts/fix-docker.sh
./scripts/fix-docker.sh

# Start the server
docker-compose up -d

# Check status
docker-compose ps
docker-compose logs -f

📦 本地安装

# Clone the repository
git clone https://github.com/ajeetraina/mcp-typescript-server.git
cd mcp-typescript-server

# Automated setup
chmod +x scripts/setup.sh
./scripts/setup.sh

# Start the server
npm start

⚡ 快速测试

运行后，测试计算器工具：

# Test calculation (replace with your method of sending JSON-RPC)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculate","arguments":{"expression":"(10+5)*2"}}}' | node dist/server.js

🛠️ 有Docker问题吗？ 检查 医生_推特.md 或奔跑 ./scripts/fix-docker.sh

🚀 特性

• 类型安全架构：使用TypeScript构建，以获得更好的开发人员体验和代码可靠性
• 生产就绪：全面的错误处理、日志记录和监控
• 容器化：Docker支持多阶段构建，以实现最佳性能
• 可扩展工具系统：易于扩展的模块化工具架构
• 安全第一：输入验证、路径限制和速率限制
• 综合测试：覆盖率>70%的单元、集成和负载测试
• CI/CD就绪：用于自动化测试和部署的GitHub Actions工作流
• 性能优化：缓存、内存管理和运行状况监视

📋 目录

• 安装
• 配置
• 可用工具
• 发展
• 测试
• API文档
• 故障排除
• 贡献
• 许可证

📦 安装

先决条件

• Node.js 18+
• npm或纱线
• Docker（可选，用于容器化部署）

来源

# Clone repository
git clone https://github.com/ajeetraina/mcp-typescript-server.git
cd mcp-typescript-server

# Install dependencies
npm install

# Copy configuration template
cp config.json config.local.json

# Build the application
npm run build

# Run tests (optional)
npm test

# Start the server
npm start

使用Docker（推荐）

# Pull and run the latest image
docker run -p 3000:3000 ajeetraina/mcp-typescript-server:latest

# Or using Docker Compose
git clone https://github.com/ajeetraina/mcp-typescript-server.git
cd mcp-typescript-server
docker-compose up

⚙️ 配置

服务器可以通过以下方式配置：

1. 配置文件 (config.json)
2. 环境变量
3. 命令行参数

配置文件示例

{
  "server": {
    "name": "typescript-mcp-server",
    "version": "1.0.0",
    "port": 3000
  },
  "logging": {
    "level": "info",
    "maxLogs": 1000
  },
  "security": {
    "allowedPaths": ["./data", "./temp"],
    "rateLimitRpm": 60
  },
  "tools": {
    "calculator": {
      "enabled": true,
      "maxExpressionLength": 100
    },
    "fileManager": {
      "enabled": true,
      "allowedExtensions": [".txt", ".json", ".md", ".csv"]
    }
  }
}

环境变量

🛠️ 可用工具

计算器工具

在支持基本算术运算的情况下进行数学计算。

{
  "method": "tools/call",
  "params": {
    "name": "calculate",
    "arguments": {
      "expression": "(10 + 5) * 2 - 8"
    }
  }
}

文件管理器工具

在允许的目录内保护文件操作。

{
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "./data/example.txt"
    }
  }
}

支持的操作：

• read_file：读取文件内容
• write_file：将内容写入文件
• list_directory：列出目录内容

可用资源

• config://server.json：当前服务器配置
• logs://recent.txt：最近的服务器日志
• health://status.json：服务器运行状况

🐳 Docker使用

快速开始

# Fix any Docker issues first
./scripts/fix-docker.sh

# Start in production mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

发展模式

# Start development environment with hot reload
docker-compose --profile dev up

# This includes:
# - Volume mounted source code
# - Automatic TypeScript compilation
# - Hot reload with nodemon

测试模式

# Run tests in container
docker-compose --profile test up

# This runs the full test suite including:
# - Unit tests
# - Integration tests
# - Coverage reports

多架构支持

Docker镜像支持两者 linux/amd64 和 linux/arm64 建筑。

# Pull specific architecture
docker pull --platform linux/arm64 ajeetraina/mcp-typescript-server:latest

👨‍💻 发展

设置开发环境

# Install dependencies
npm install

# Create data directories
mkdir -p data temp logs

# Start development server with hot reload
npm run dev

# Or using Docker
docker-compose --profile dev up

代码的风格

该项目使用ESLint和Prettier进行代码格式化：

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code with Prettier
npx prettier --write "src/**/*.ts"

添加新工具

1. 在中创建新的工具类 src/tools/:

import { ToolDefinition, ToolResult } from '../types/index.js';

export class MyCustomTool {
  getDefinition(): ToolDefinition {
    return {
      name: 'my_tool',
      description: 'Description of what the tool does',
      inputSchema: {
        type: 'object',
        properties: {
          param1: {
            type: 'string',
            description: 'Parameter description',
          },
        },
        required: ['param1'],
      },
    };
  }

  async execute(args: { param1: string }): Promise {
    // Tool implementation
    return {
      content: [{
        type: 'text',
        text: `Result: ${args.param1}`,
      }],
    };
  }
}

1. 在中注册该工具 src/server.ts:

import { MyCustomTool } from './tools/myCustomTool.js';

// In initializeTools method
const myTool = new MyCustomTool();
this.tools.set('my_tool', myTool);

🧪 测试

运行测试

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test -- server.test.ts

# Run integration tests
npm test -- integration.test.ts

# Run load tests
npm test -- load.test.ts

测试类型

• 单元测试：测试单个组件和功能
• 集成测试：测试服务器启动和MCP协议通信
• 负载测试：并发请求下的测试性能
• 安全测试：测试输入验证和安全措施

覆盖范围要求

• 分支机构：70%
• 功能：70%
• 线路：70%
• 声明：70%

📚 API文档

MCP协议方法

列出工具

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

呼叫工具

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "calculate",
    "arguments": {
      "expression": "2 + 3 * 4"
    }
  }
}

列出资源

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/list",
  "params": {}
}

读取资源

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/read",
  "params": {
    "uri": "config://server.json"
  }
}

健康检查端点

服务器通过 health://status.json 资源：

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "uptime": 123456,
  "memory": {
    "used": 45678901,
    "total": 67890123
  },
  "tools": {
    "calculator": true,
    "fileManager": true
  }
}

🛠️ 故障排除

常见问题

1.Docker构建失败

问题：包锁文件不匹配或生成上下文问题。

解决方案:

# Use the automated fix
./scripts/fix-docker.sh

# Or manual fix
git pull origin main
rm -rf node_modules package-lock.json
npm install
docker-compose build --no-cache

2.TypeScript编译错误

问题：类型不匹配或缺少依赖项。

解决方案:

# Pull latest fixes
git pull origin main

# Clean and rebuild
npm run clean
npm install
npm run build

3.端口已在使用中

问题：端口3000已被占用。

解决方案:

# Find and kill process
lsof -i :3000
kill -9 

# Or use different port
PORT=3001 npm start

4.权限错误

问题：无法写入数据目录。

解决方案:

# Fix permissions
sudo chown -R $USER:$USER data temp logs

# Or recreate directories
rm -rf data temp logs
mkdir -p data temp logs

获取帮助

• Docker问题：检查 医生_推特.md
• 快速开始：参见 QUICKSTART.md
• GitHub问题：用于错误报告和功能请求
• GitHub讨论：用于提问和社区支持

🚀 部署

生产部署

使用Docker

# Build production image
docker build -t mcp-typescript-server:latest .

# Run in production mode
docker run -d \
  --name mcp-server \
  --restart unless-stopped \
  -p 3000:3000 \
  -v /path/to/data:/app/data \
  -v /path/to/config.json:/app/config.json:ro \
  -e NODE_ENV=production \
  mcp-typescript-server:latest

使用流程管理器（PM2）

# Install PM2
npm install -g pm2

# Build the application
npm run build

# Start with PM2
pm2 start dist/server.js --name "mcp-server"

# Monitor
pm2 monit

# View logs
pm2 logs mcp-server

Kubernetes部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-typescript-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-typescript-server
  template:
    metadata:
      labels:
        app: mcp-typescript-server
    spec:
      containers:
      - name: mcp-server
        image: ajeetraina/mcp-typescript-server:latest
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: "production"
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "200m"

监测和可观察性

• 健康检查：内置健康监测
• 日志记录：具有可配置级别的结构化日志记录
• 指标：内存使用和性能监控
• 错误跟踪：全面的错误处理和报告

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

开发工作流程

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/amazing-feature
3. 进行更改
4. 添加新功能的测试
5. 确保所有测试通过： npm test
6. 打开你的代码： npm run lint
7. 提交您的更改： git commit -m 'Add amazing feature'
8. 推到分支： git push origin feature/amazing-feature
9. 打开拉取请求

行为准则

该项目遵循 贡献者契约行为准则.

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

📞 支持

• 文档:
• 问题:
• 讨论:
• Docker问题: 医生_推特.md

🙏 致谢

• 模型上下文协议 对于协议规范
• TypeScript 令人惊叹的字体系统
• 所有帮助改进此项目的贡献者

______________________________________________________________________

内置于❤️ 由社区为各地的AI开发人员提供。