Installing mcp-scan as a Go Library

This guide explains how to install and configure mcp-scan for use as a library in your Go projects.

---

Prerequisites

• Go 1.24 or higher
• Go modules enabled (GO111MODULE=on)

---

Installation

1. Add the dependency

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

Or specifying a specific version:

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

2. Import the package

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

---

Package Structure

mcp-scan exposes a public API through the pkg/scanner package. Internal packages (internal/) are not available for external use.

github.com/mcphub/mcp-scan/
    pkg/
        scanner/          <- Main public API
    internal/             <- Internal implementation (not exported)
        types/            <- Shared types
        surface/          <- MCP surface extraction
        msss/             <- MSSS score calculation
        baseline/         <- Baseline management
        ...

Importable Packages

Package	Import Path	Use
Scanner	github.com/mcphub/mcp-scan/pkg/scanner	Main API

Support types like Finding, Severity, etc. are embedded in the scanner package structures.

---

Installation Verification

Create a test file to verify the installation is correct:

// test_install.go
package main

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

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

func main() {
    // Create temporary directory with test file
    tmpDir, err := os.MkdirTemp("", "mcp-scan-test")
    if err != nil {
        log.Fatal(err)
    }
    defer os.RemoveAll(tmpDir)

    // Create test Python file
    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)
    }

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

    fmt.Println("mcp-scan installed successfully!")
    fmt.Printf("Files scanned: %d\n", result.Manifest.TotalFiles)
    fmt.Printf("Findings: %d\n", len(result.Findings))
}

Run:

go run test_install.go

Expected output:

mcp-scan installed successfully!
Files scanned: 1
Findings: 1

---

Development Environment Configuration

Optional Environment Variables

mcp-scan does not require environment variables to function. However, the following may be useful:

Variable	Description	Default Value
MCP_SCAN_WORKERS	Number of parallel workers	runtime.NumCPU()

Build Dependencies

mcp-scan uses tree-sitter for code parsing. The native tree-sitter libraries are included as Go bindings and compile automatically.

If you experience build issues on systems without a C compiler:

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

# macOS
xcode-select --install

# Windows
# Install MinGW-w64 or use WSL

---

Updating

To update to the latest version:

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

To update to a specific version:

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

---

Versioning

mcp-scan follows Semantic Versioning:

• MAJOR: Incompatible API changes
• MINOR: New backward-compatible functionality
• PATCH: Backward-compatible bug fixes

---

Common Issues

Error: "cannot find module"

Make sure Go modules are enabled:

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

Error: "cgo: C compiler not found"

Install C development tools (see build dependencies section above).

Error: "version not found"

Verify you are using an existing version:

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

---

Next Step

See the Public API Reference to learn about all available types and methods.