Instalacion de mcp-scan como Libreria Go¶

Esta guia explica como instalar y configurar mcp-scan para usarlo como libreria en tus proyectos Go.

Requisitos Previos¶

Go 1.24 o superior
Modulos Go habilitados (GO111MODULE=on)

Instalacion¶

1. Agregar la dependencia¶

go get github.com/mcphub/mcp-scan@latest

O especificando una version concreta:

go get github.com/mcphub/mcp-scan@v2.0.0

2. Importar el paquete¶

import "github.com/mcphub/mcp-scan/pkg/scanner"

Estructura de Paquetes¶

mcp-scan expone una API publica a traves del paquete pkg/scanner. Los paquetes internos (internal/) no estan disponibles para uso externo.

github.com/mcphub/mcp-scan/
    pkg/
        scanner/          <- API publica principal
    internal/             <- Implementacion interna (no exportada)
        types/            <- Tipos compartidos
        surface/          <- Extraccion de superficie MCP
        msss/             <- Calculo de puntuacion MSSS
        baseline/         <- Gestion de lineas base
        ...

Paquetes Importables¶

Paquete	Import Path	Uso
Scanner	`github.com/mcphub/mcp-scan/pkg/scanner`	API principal

Los tipos de soporte como Finding, Severity, etc. estan embebidos en las estructuras del paquete scanner.

Verificacion de la Instalacion¶

Crea un archivo de prueba para verificar que la instalacion es correcta:

// test_install.go
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "path/filepath"

    "github.com/mcphub/mcp-scan/pkg/scanner"
)

func main() {
    // Crear directorio temporal con archivo de prueba
    tmpDir, err := os.MkdirTemp("", "mcp-scan-test")
    if err != nil {
        log.Fatal(err)
    }
    defer os.RemoveAll(tmpDir)

    // Crear archivo Python de prueba
    testFile := filepath.Join(tmpDir, "server.py")
    testCode := `
import os
from mcp import tool

@tool
def execute_command(cmd: str) -> str:
    return os.system(cmd)  # Vulnerable!
`
    if err := os.WriteFile(testFile, []byte(testCode), 0644); err != nil {
        log.Fatal(err)
    }

    // Ejecutar escaneo
    cfg := scanner.DefaultConfig()
    s := scanner.New(cfg)
    result, err := s.Scan(context.Background(), tmpDir)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("mcp-scan instalado correctamente!")
    fmt.Printf("Archivos escaneados: %d\n", result.Manifest.TotalFiles)
    fmt.Printf("Hallazgos: %d\n", len(result.Findings))
}

Ejecutar:

go run test_install.go

Salida esperada:

mcp-scan instalado correctamente!
Archivos escaneados: 1
Hallazgos: 1

Configuracion del Entorno de Desarrollo¶

Variables de Entorno Opcionales¶

mcp-scan no requiere variables de entorno para funcionar. Sin embargo, las siguientes pueden ser utiles:

Variable	Descripcion	Valor por defecto
`MCP_SCAN_WORKERS`	Numero de workers paralelos	`runtime.NumCPU()`

Dependencias de Compilacion¶

mcp-scan utiliza tree-sitter para el parsing de codigo. Las librerias nativas de tree-sitter estan incluidas como bindings Go y se compilan automaticamente.

Si experimentas problemas de compilacion en sistemas sin compilador C:

# Linux (Debian/Ubuntu)
sudo apt-get install build-essential

# macOS
xcode-select --install

# Windows
# Instalar MinGW-w64 o usar WSL

Actualizacion¶

Para actualizar a la ultima version:

go get -u github.com/mcphub/mcp-scan@latest

Para actualizar a una version especifica:

go get github.com/mcphub/mcp-scan@v2.1.0

Versionado¶

mcp-scan sigue Versionado Semantico:

MAJOR: Cambios incompatibles en la API
MINOR: Nueva funcionalidad compatible hacia atras
PATCH: Correcciones de bugs compatibles hacia atras

Problemas Comunes¶

Error: "cannot find module"¶

Asegurate de que los modulos Go estan habilitados:

export GO111MODULE=on
go mod init tu-proyecto
go get github.com/mcphub/mcp-scan@latest

Error: "cgo: C compiler not found"¶

Instala las herramientas de desarrollo de C (ver seccion de dependencias de compilacion arriba).

Error: "version not found"¶

Verifica que estas usando una version existente:

go list -m -versions github.com/mcphub/mcp-scan

Siguiente Paso¶

Consulta la Referencia de API Publica para conocer todos los tipos y metodos disponibles.