mrch4n/node-mcp-server

TypeScript MCP Server

A Model Context Protocol (MCP) server built in TypeScript that provides tools for interacting with GitHub and other services.

Features

• 🔍 GitHub Integration: Search repositories, get user information, view repository details, list issues, and get pull request details
• 🛠️ Extensible Architecture: Easy to add new service integrations
• 📝 TypeScript: Full type safety and modern development experience
• 🚀 MCP Protocol: Compatible with MCP clients and tools
• 📊 Structured Logging: Configurable logging levels

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn package manager
• GitHub Personal Access Token (for GitHub features)

Installation

1. Clone the repository:

git clone <repository-url>
cd ts-mcp-server

2. Install dependencies:

npm install

3. Set up environment variables:

cp env.example .env

4. Edit .env and add your GitHub token:

GITHUB_TOKEN=your_github_personal_access_token

Configuration

Environment Variables

GitHub Token Setup

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Click "Generate new token (classic)"
3. Select the following scopes:
   • public_repo (for public repository access)
   • read:user (for user information)
   • read:org (for organization access, if needed)
4. Copy the token and add it to your .env file

Usage

Development Mode

Run the server in development mode with hot reloading:

npm run dev

Production Mode

Build and run the server:

npm run build
npm start

Testing

Run the test suite:

npm test

Run tests in watch mode:

npm run test:watch

Available Tools

GitHub Tools

github_search_repositories

Search for GitHub repositories.

Parameters:

• query (string, required): Search query
• limit (number, optional): Maximum number of results (default: 10)

Example:

{
  "name": "github_search_repositories",
  "arguments": {
    "query": "typescript mcp server",
    "limit": 5
  }
}

github_get_user_info

Get information about a GitHub user.

Parameters:

• username (string, required): GitHub username

Example:

{
  "name": "github_get_user_info",
  "arguments": {
    "username": "octocat"
  }
}

github_get_repository

Get detailed information about a specific repository.

Parameters:

• owner (string, required): Repository owner
• repo (string, required): Repository name

Example:

{
  "name": "github_get_repository",
  "arguments": {
    "owner": "microsoft",
    "repo": "vscode"
  }
}

github_list_issues

List issues for a repository.

Parameters:

• owner (string, required): Repository owner
• repo (string, required): Repository name
• state (string, optional): Issue state - "open", "closed", or "all" (default: "open")
• limit (number, optional): Maximum number of issues (default: 10)

Example:

{
  "name": "github_list_issues",
  "arguments": {
    "owner": "microsoft",
    "repo": "vscode",
    "state": "open",
    "limit": 5
  }
}

github_get_pr

Get detailed information about a specific pull request.

Parameters:

• owner (string, required): Repository owner
• repo (string, required): Repository name
• pull_number (number, required): Pull request number

Example:

{
  "name": "github_get_pr",
  "arguments": {
    "owner": "microsoft",
    "repo": "vscode",
    "pull_number": 12345
  }
}

Architecture

src/
├── index.ts              # Main server entry point
├── services/
│   └── github.ts         # GitHub API integration
├── types/
│   └── index.ts          # TypeScript type definitions
└── utils/
    └── logger.ts         # Logging utility

Extending the Server

Adding New Services

1. Create a new service file in src/services/
2. Implement the service class with required methods
3. Add the service to the main server in src/index.ts
4. Define new tools in the ListToolsRequestSchema handler
5. Implement tool logic in the CallToolRequestSchema handler

Example Service Structure

export class NewService {
  constructor() {
    // Initialize service
  }

  async someMethod(params: unknown) {
    // Implement method logic
    return {
      content: [
        {
          type: 'text',
          text: 'Result text'
        }
      ]
    };
  }
}

Development

Code Quality

• Linting: npm run lint
• Lint Fix: npm run lint:fix
• Type Checking: npm run build

Building

npm run build

The compiled JavaScript will be output to the dist/ directory.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Troubleshooting

Common Issues

1. GitHub API Rate Limiting: Ensure you have a valid GitHub token
2. Permission Errors: Check that your GitHub token has the required scopes
3. Build Errors: Make sure you're using Node.js 18+ and all dependencies are installed

Debug Mode

Set LOG_LEVEL=debug in your .env file for detailed logging.

Resources

• Model Context Protocol
• GitHub API Documentation
• Octokit.js Documentation
• TypeScript Documentation