Jules

Agente de codificación asíncrona Jules - ejecuta tareas autónomas usando Jules

GitHub
41
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Jules (jules-mcp)

Un servidor MCP (Protocolo de Contexto de Modelo) que expone las operaciones del Agente Jules de Google a través de FastMCP.

Este servidor permite a clientes compatibles con MCP (y código Python) listar fuentes de Jules, crear y gestionar sesiones, e inspeccionar actividades utilizando el SDK oficial jules-agent-sdk.

  • Marco del servidor: FastMCP
  • SDK: jules-agent-sdk
  • Python: 3.13+
  • Licencia: Apache-2.0

Características

Herramientas expuestas a través del servidor MCP (agrupadas por área):

  • Fuentes
    • get_source(source_id)
    • list_sources(filter_str=None, page_size=None, page_token=None)
    • get_all_sources(filter_str=None)
  • Sesiones
    • create_session(prompt, source, starting_branch=None, title=None, require_plan_approval=False)
    • get_session(session_id)
    • list_sessions(page_size=None, page_token=None)
    • approve_session_plan(session_id)
    • send_session_message(session_id, prompt)
    • wait_for_session_completion(session_id, poll_interval=5, timeout=600)
  • Actividades
    • get_activity(session_id, activity_id)
    • list_activities(session_id, page_size=None, page_token=None)
    • list_all_activities(session_id)

Consulte jules_mcp/jules_mcp.py para ver las firmas y docstrings integrados.

Instalación

Opción A — desde un checkout local:

# from the repository root
pip install -e .

Opción B — usando uv (recomendado durante el desarrollo):

# from the repository root
uv sync

El proyecto está dirigido a Python 3.13+.

Configuración

Establezca su clave de API de Jules mediante una variable de entorno:

  • Windows PowerShell 
    $Env:JULES_API_KEY = "<your_api_key_here>"
  • Shells Unix (bash/zsh) 
    export JULES_API_KEY="<your_api_key_here>"

Si no proporciona un argumento a jules(), el SDK lee JULES_API_KEY automáticamente.

Ejecución del servidor MCP

Hay dos formas comunes de ejecutar el servidor.

  1. Ejecución programática (en proceso) usando el Cliente FastMCP — útil para pruebas o integración:
import asyncio
from fastmcp import Client
from jules_mcp import mcp

async def main():
    async with Client(mcp) as client:
        # Example: list all sources (auto-paginated)
        result = await client.call_tool("get_all_sources")
        print(result)

asyncio.run(main())
  1. Como ejecutable de servidor MCP independiente para clientes MCP externos:

  • Usando uv y FastMCP directamente

    uv run fastmcp run jules_mcp/jules_mcp.py:mcp

    Esto inicia el servidor MCP a través de stdio.

  • Usando los archivos de configuración proporcionados

    • MCP.json: una configuración de comando de ejemplo para hosts compatibles con MCP.
    • fastmcp.json: configuración de entorno/ejecución de FastMCP.

Ajuste las rutas en MCP.json si utiliza una ubicación de checkout diferente.

También puede ejecutar a través del punto de entrada del módulo:

python -m jules_mcp

Esto llama a start_mcp() que invoca FastMCP.run() usando la instancia "mcp" definida en el paquete.

Notas de uso y ejemplos

  • Listar y filtrar fuentes
import asyncio
from fastmcp import Client
from jules_mcp import mcp

async def main():
    async with Client(mcp) as client:
        # Filter syntax follows AIP-160 filtering rules supported by Jules
        res = await client.call_tool(
            "list_sources",
            {"filter_str": "name=sources/source1 OR name=sources/source2", "page_size": 10}
        )
        print(res)

asyncio.run(main())
  • Crear una sesión y esperar su finalización
import asyncio
from fastmcp import Client
from jules_mcp import mcp

async def run_session():
    async with Client(mcp) as client:
        session = await client.call_tool(
            "create_session",
            {
                "prompt": "Analyze the repository and propose improvements",
                "source": "sources/abc123",
                "require_plan_approval": True,
            },
        )

        # Optionally approve plan
        await client.call_tool("approve_session_plan", {"session_id": session["name"]})

        # Wait for completion
        final = await client.call_tool(
            "wait_for_session_completion",
            {"session_id": session["name"], "poll_interval": 5, "timeout": 600}
        )
        print(final)

asyncio.run(run_session())
  • Inspeccionar actividades
import asyncio
from fastmcp import Client
from jules_mcp import mcp

async def list_acts(session_id: str):
    async with Client(mcp) as client:
        acts = await client.call_tool("list_all_activities", {"session_id": session_id})
        for a in acts:
            print(a)

asyncio.run(list_acts("sessions/abc123"))

Desarrollo

  • Cree un entorno virtual e instale las dependencias de desarrollo

    uv sync
# or: pip install -e .[dev]

  • Ejecute las pruebas (nota: algunas herramientas pueden acceder a la API de Jules y requieren JULES_API_KEY)

    uv run pytest -q

  • Linting/formato: siga sus herramientas preferidas; este repositorio no incluye linters por defecto.

Metadatos del proyecto

  • Nombre del paquete: jules-mcp
  • Versión: 0.1.0
  • Puntos de entrada:
    • Módulo Python: python -m jules_mcp
    • Fuente FastMCP: jules_mcp/jules_mcp.py:mcp

Licencia

Licencia Apache 2.0. Consulte el archivo LICENSE para más detalles.

Agradecimientos