🔌 my_MCPServer

Un serveur Model Context Protocol qui connecte GitHub à Claude Desktop

---

Fonctionnalités

• 📁 Repositories — Lister, consulter et rechercher parmi tous vos dépôts
• 🐛 Issues — Parcourir les issues ouvertes/fermées, lire les détails, en créer de nouvelles
• 🗂️ Fichiers — Naviguer dans l'arborescence et lire le contenu des fichiers
• 🔒 Dépôts privés — Fonctionne avec un token authentifié, y compris les repos privés
• ⚡ Sans configuration — Un simple GITHUB_TOKEN suffit

---

Stack technique

Couche	Technologie
Langage	TypeScript 5.x
Runtime	Node.js 18+
MCP	@modelcontextprotocol/sdk
Validation	zod
Build	tsc + tsc-alias
Tests	Jest + ts-jest

---

Démarrage rapide

Prérequis

• Node.js 18 ou supérieur
• Un token d'accès personnel GitHub (classic)
  • Scopes requis : repo, read:user

1. Cloner le dépôt

git clone https://github.com/KitetsuK/my_MCPServer.git
cd my_MCPServer

2. Installer les dépendances

npm install

3. Configurer le token

Créer un fichier .env à la racine :

GITHUB_TOKEN=ghp_votre_token_ici

4. Compiler

npm run build

5. Configurer Claude Desktop

Ouvrir C:\Users\{vous}\AppData\Roaming\Claude\claude_desktop_config.json et ajouter :

{
  "mcpServers": {
    "my_MCPServer": {
      "command": "node",
      "args": ["C:\\chemin\\vers\\my_MCPServer\\build\\index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_votre_token_ici"
      }
    }
  }
}

Relancer Claude Desktop — les outils seront disponibles immédiatement.

📖 Guide complet : documentation/configuration-claude-desktop.md

---

Outils disponibles

Outil	Description
list_repositories	Liste tous les repositories de l'utilisateur authentifié
get_repository	Détails d'un repository (ex : KitetsuK/my_MCPServer)
search_repositories	Recherche par requête (ex : language:typescript stars:>100)
list_issues	Liste les issues d'un repository, filtrable par état
get_issue	Détails d'une issue par numéro
create_issue	Crée une nouvelle issue sur un repository
list_files	Liste les fichiers d'un répertoire
get_file_content	Lit le contenu d'un fichier spécifique

---

Architecture

Ce projet suit l'architecture hexagonale (Ports & Adaptateurs) avec les principes du Domain-Driven Design.

Claude Desktop
     │
     ▼ MCP (stdio)
┌─────────────────────────────────────┐
│          Couche Interface           │
│   McpServerBootstrap + *McpTools    │  ← adaptateurs primaires (entrants)
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│         Couche Application          │
│         Use Cases (execute)         │  ← orchestration
└─────────────────┬───────────────────┘
                  │ ports (interfaces)
┌─────────────────▼───────────────────┐
│            Couche Domaine           │
│    Entités · Value Objects · Ports  │  ← logique métier pure, sans dépendances
└─────────────────┬───────────────────┘
                  │ implémente les ports
┌─────────────────▼───────────────────┐
│       Couche Infrastructure         │
│  Adaptateurs · Mappers · HttpClient │  ← adaptateurs secondaires (sortants)
└─────────────────┬───────────────────┘
                  │
                  ▼ HTTPS
            GitHub REST API

Flux d'une requête

Claude Desktop → *McpTools → UseCase.execute() → Port → Adapter → GitHub API
                                   │
                               Formatter → texte lisible → Claude Desktop

---

Structure du projet

src/
├── shared/                    # Transversal — utilisé par toutes les couches
│   ├── exceptions/            # Hiérarchie ApplicationException
│   └── logger/                # Port ILogger + ConsoleLogger (stderr uniquement)
│
├── github/
│   ├── domain/                # Logique métier pure — aucune dépendance externe
│   │   ├── entities/          # Repository, Issue, File, FileContent
│   │   ├── value-objects/     # IssueState, FileType
│   │   ├── ports/             # IRepositoryPort, IIssuePort, IFilePort
│   │   └── exceptions/        # GitHubApiException
│   │
│   ├── infrastructure/        # Adaptateurs sortants
│   │   ├── dto/               # Types bruts des réponses de l'API GitHub
│   │   ├── http/              # GitHubHttpClient + config
│   │   ├── mappers/           # DTO → entité domaine
│   │   └── adapters/          # Implémentations des ports
│   │
│   └── application/
│       └── use-cases/         # ListRepositories, GetIssue, CreateIssue…
│
└── interface/
    └── mcp/
        ├── tools/             # Enregistrement des outils MCP (adaptateurs entrants)
        ├── formatters/        # Entité domaine → texte lisible
        └── McpServerBootstrap.ts

---

Tests

# Tests unitaires uniquement
npm run test:unit

# Tests d'intégration (nécessite .env avec GITHUB_TOKEN)
npm run test:integration

Les tests utilisent Jest + ts-jest en mode ESM. Les ports sont mockés avec jest.fn() — l'HTTP n'est jamais mocké directement.

tests/
├── unit/
│   ├── domain/models/              # Comportement des entités
│   ├── infrastructure/mappers/     # Conversion DTO → entité
│   └── application/use-cases/      # Orchestration des use cases
└── integration/
    └── github/                     # Appels HTTP réels vers l'API GitHub

---