Janus Mcp

Serveur MCP local qui relie OpenCode à vos instances auto-hébergées de GitLab, Jira et Confluence - le tout via un canal stdio sécurisé.

Sommaire

• Présentation
• Fonctionnalités
• Prérequis
• Installation
• Configuration
• Connexion à un agent
• Désinstallation
• Utilisation transparente
• Référence des outils
• Sécurité
• Licence

Présentation

Janus MCP fait le pont entre votre agent OpenCode et vos outils d'entreprise. Le nom rend hommage à Janus, dieu romain des ponts, des passages et des transitions - celui qui regarde des deux côtés, exactement comme ce serveur qui fait transiter les appels entre deux mondes :

OpenCode --stdio--> Janus MCP --HTTPS--> GitLab / Jira / Confluence

L'agent OpenCode appelle un outil MCP. Janus traduit cet appel en requête HTTP vers l'API cible, puis renvoie le résultat à l'agent.

Fonctionnalités

• 🔎 Lecture : issues et merge requests, recherches JQL/CQL.
• ✍️ Écriture : création d'issues/pages/merge requests, ajout de commentaires.
• 🔒 Local & minimal : tourne en stdio sur votre machine, jamais exposé en HTTP.
• 🔑 Zéro secret en dur : tous les jetons proviennent des variables d'environnement.

Prérequis

Pour utiliser Janus MCP (binaire précompilé, aucune compilation requise) :

• curl (ou wget)
• Linux ou macOS (Windows : voir l'archive .zip)
• Accès réseau aux instances GitLab / Jira / Confluence (VPN si nécessaire)
• Un jeton d'accès personnel par service (voir Configuration)

Installation

Binaire précompilé — une seule commande, aucune dépendance :

curl -fsSL https://gitlab.com/api/v4/projects/mypublicfolder%2Fjanus-mcp/packages/generic/janus-mcp/latest/install.sh | bash

Le script détecte votre OS/architecture, télécharge l'archive depuis le registre GitLab, puis installe :

• le binaire dans ~/.local/bin/janus-mcp ;
• un modèle de config dans ~/.config/janus-mcp/.env (à remplir ensuite).

💡 Ajoutez ~/.local/bin à votre PATH s'il n'y est pas déjà : export PATH="$HOME/.local/bin:$PATH".

Installer une version précise :

curl -fsSL https://gitlab.com/api/v4/projects/mypublicfolder%2Fjanus-mcp/packages/generic/janus-mcp/latest/install.sh | JANUS_MCP_VERSION=v0.1.0 bash

Configuration

Le binaire cherche la config dans cet ordre :

1. le fichier pointé par JANUS_MCP_ENV_FILE (si défini) ;
2. ~/.config/janus-mcp/.env (emplacement standard installé par install.sh) ;
3. .env du répertoire courant (développement).

Un service est optionnel : laissez son URL et son TOKEN vides pour le désactiver, le serveur démarre avec les seuls services renseignés.

Pour un développement en local, copiez le fichier d'exemple puis remplissez les valeurs :

cp .env.example .env

# URL des instances
GITLAB_URL=https://gitlab.example.com
JIRA_URL=https://jira.example.com
CONFLUENCE_URL=https://confluence.example.com

# Jetons d'accès (jamais coder en dur)
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
JIRA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx
CONFLUENCE_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx

# Timeout des requêtes en secondes (optionnel, défaut 30)
GITLAB_TIMEOUT=
JIRA_TIMEOUT=
CONFLUENCE_TIMEOUT=

⚠️ Le fichier .env est ignoré par Git. Ne le committez jamais.

Connexion à un agent

Une fois le binaire installé et le .env renseigné, référencez Janus comme serveur MCP local. La config (~/.config/janus-mcp/.env) est chargée automatiquement, aucun cwd à préciser.

OpenCode

Ajoutez l'entrée janus-mcp à votre opencode.json (remplacez $HOME par votre chemin absolu, ex. /home/jean-luc) :

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "janus-mcp": {
      "type": "local",
      "command": ["$HOME/.local/bin/janus-mcp"],
      "enabled": true
    }
  }
}

Vous pouvez aussi utiliser la commande interactive opencode mcp add et choisir le binaire ~/.local/bin/janus-mcp.

Claude Code

claude mcp add janus-mcp -- "$HOME/.local/bin/janus-mcp"

Autres clients MCP

Tout client MCP stdio fait l'affaire : pointez-le vers ~/.local/bin/janus-mcp sans argument. La configuration provient de ~/.config/janus-mcp/.env (ou des variables d'environnement, voir Configuration).

Une fois configuré, demandez à l'agent d'utiliser les outils par leur nom, par exemple :

Récupère l'issue PROJ-123 avec get_jira_issue.

Désinstallation

Pour supprimer complètement Janus MCP :

1. Référence dans l'agent : retirez l'entrée janus-mcp du bloc mcp de votre opencode.json (ou claude mcp remove janus-mcp pour Claude Code), puis redémarrez votre agent. C'est cette étape qui arrête réellement le serveur : il est lancé (et relancé) par l'agent.

2. Processus en cours : le serveur est un processus enfant de l'agent ; le tuer à la main est sans effet durable car l'agent le relance. Sous Linux, supprimer le binaire n'arrête pas non plus un processus déjà en mémoire. Vérifiez qu'il a bien disparu après le redémarrage de l'agent :

   pgrep -af janus-mcp

   (S'il reste un processus, terminez-le : pkill -f janus-mcp.)

3. Binaire :

   rm -f ~/.local/bin/janus-mcp

4. Configuration et jetons :

   rm -rf ~/.config/janus-mcp

💡 Si vous aviez choisi un dossier différent via JANUS_MCP_BIN_DIR ou JANUS_MCP_CONFIG_DIR, supprimez ces chemins à la place.

Utilisation transparente

L'utilisateur n'a pas besoin de connaître les noms des outils : chaque outil porte une description explicite (rôle + moment d'usage), que l'agent reçoit automatiquement. Il suffit de formuler la demande normalement :

Quelle est l'issue PROJ-123 ? · Trouve les issues ouvertes du projet DEV · Cherche la page sur la politique de sécurité · Ouvre la MR !42 de group/project

Les actions d'écriture (créer, commenter) ne sont déclenchées que si la demande est explicite, conformément à leur description.

Renforcer avec des instructions (optionnel)

Pour garantir le comportement, collez ce bloc dans les règles de votre agent (le AGENTS.md du projet pour OpenCode, CLAUDE.md pour Claude Code) :

# Outils d'entreprise (Janus MCP)

Quand l'utilisateur évoque une issue, un ticket, une merge request ou de la
documentation, utilise les outils MCP disponibles :

- Jira : `get_jira_issue` (issue précise), `search_jira_issues` (recherche JQL).
- Confluence : `get_confluence_page` (page précise), `search_confluence` (CQL).
- GitLab : `get_gitlab_mr` / `list_gitlab_mrs` (merge requests).

Les outils d'écriture (`add_comment`, `update_jira_comment`,
`create_jira_issue`, `update_jira_issue`, `add_jira_issue_link`, `add_jira_web_link`,
`create_confluence_page`, `update_confluence_page`, `move_confluence_page`,
`create_gitlab_mr`, `comment_gitlab_mr`) ne s'exécutent que sur demande
explicite de l'utilisateur.

English version:

# Enterprise tools (Janus MCP)

When the user mentions an issue, ticket, merge request, or documentation, use
the available MCP tools:

- Jira: `get_jira_issue` (specific issue), `search_jira_issues` (JQL search).
- Confluence: `get_confluence_page` (specific page), `search_confluence` (CQL).
- GitLab: `get_gitlab_mr` / `list_gitlab_mrs` (merge requests).

Write tools (`add_comment`, `update_jira_comment`, `create_jira_issue`,
`update_jira_issue`, `add_jira_issue_link`, `add_jira_web_link`, `create_confluence_page`,
`update_confluence_page`, `move_confluence_page`, `create_gitlab_mr`,
`comment_gitlab_mr`) run only on explicit user request.

Référence des outils

Jira

Confluence

GitLab

Sécurité

• Aucun secret en dur : les jetons sont lus exclusivement depuis .env.
• Périmètre minimal : seuls les outils listés ci-dessus sont exposés. Aucun outil de suppression.
• Exécution locale : le serveur tourne via stdio sur votre machine, jamais en HTTP public.
• Les jetons ne sont jamais journalisés ni inclus dans les messages d'erreur.

Licence

Business Source License 1.1 - Licensor : Jean-Luc Boulétreau.

Licensed Work : janus-mcp · Change Date : 6666-12-31 · Change License : MIT.

La BSL 1.1 n'est pas une licence open source. L'œuvre sous licence passera sous la Change License (MIT) à la Change Date.