AI/xdebug-mcp
1
0
Fork 0
Code Releases 1 Activity Actions
xdebug-mcp/docs/superpowers/plans/2026-05-12-xdebug-mcp.md

1301 lines
34 KiB
Markdown
Raw Normal View History

docs: add xdebug-mcp implementation plan
2026-05-12 07:30:10 +00:00
# xdebug-mcp Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Build a Go MCP server that parses Xdebug cachegrind profiling files and exposes three analysis tools: `analyze_profile`, `get_callers`, `get_callees`.
**Architecture:** Full in-memory parse + LRU cache (capacity 2). Each tool receives `file_path` as a direct parameter. The mcp-framework bootstrap CLI wraps the MCP server; `mark3labs/mcp-go` handles the JSON-RPC stdio protocol. Business logic (Analyze/Callers/Callees functions) is separated from I/O to keep tests simple.
**Tech Stack:** Go 1.22+, `mark3labs/mcp-go` (MCP protocol), `forge.lclr.dev/AI/mcp-framework` (bootstrap CLI + manifest), `github.com/stretchr/testify` (tests)
---
## File Map
| File | Role |
|------|------|
| `go.mod` | Module definition |
| `mcp.toml` | Manifest source (read by mcp-framework generate) |
| `mcpgen/manifest.go` | Generated — manifest loader |
| `mcpgen/metadata.go` | Generated — BinaryName, DefaultDescription |
| `mcpgen/update.go` | Generated — update helpers |
| `mcpgen/secretstore.go` | Generated — secret store helpers |
| `cmd/xdebug-mcp/main.go` | Entry point — delegates to app.Run |
| `internal/cachegrind/model.go` | Profile, Function, Call types |
| `internal/cachegrind/parser.go` | Streaming parser, gzip support |
| `internal/cachegrind/parser_test.go` | Parser tests with inline fixture |
| `internal/cache/lru.go` | LRU cache with modtime invalidation |
| `internal/cache/lru_test.go` | Cache tests |
| `internal/tools/shared.go` | loadProfile, findFunctions, formatCosts helpers |
| `internal/tools/analyze.go` | AnalyzeTool, AnalyzeHandler, Analyze function |
| `internal/tools/callers.go` | CallersTool, CallersHandler, Callers function |
| `internal/tools/callees.go` | CalleesTool, CalleesHandler, Callees function |
| `internal/tools/tools_test.go` | Tools tests (no file I/O — uses constructed Profile) |
| `internal/app/app.go` | Wires bootstrap + MCP server + tools |
---
## Task 1: Project scaffold
**Files:**
- Create: `go.mod`
- Create: `mcp.toml`
- Create: `mcpgen/` (generated)
- [ ] **Init go module**
```bash
cd /home/leclere/Projets/IA/xdebug-mcp
go mod init forge.lclr.dev/AI/xdebug-mcp
```
Expected: `go.mod` created with `module forge.lclr.dev/AI/xdebug-mcp`
- [ ] **Create mcp.toml**
```toml
binary_name = "xdebug-mcp"
[bootstrap]
description = "MCP server for Xdebug profiling files"
[profiles]
default = "prod"
known = ["dev", "prod"]
```
- [ ] **Install mcp-framework CLI and generate mcpgen**
```bash
go install forge.lclr.dev/AI/mcp-framework/cmd/mcp-framework@latest
mcp-framework generate
ls mcpgen/
```
Expected: `manifest.go metadata.go secretstore.go update.go`
- [ ] **Add dependencies**
```bash
go get forge.lclr.dev/AI/mcp-framework
go get github.com/mark3labs/mcp-go
go get github.com/stretchr/testify
go mod tidy
```
- [ ] **Commit**
```bash
git add go.mod go.sum mcp.toml mcpgen/
git commit -m "chore: scaffold project, generate mcpgen, add dependencies"
```
---
## Task 2: Data model
**Files:**
- Create: `internal/cachegrind/model.go`
- [ ] **Create model.go**
```go
package cachegrind
// Profile holds the parsed contents of a cachegrind file.
type Profile struct {
Cmd string
Events []string
Functions []*Function
ByName map[string][]*Function // one name may appear in multiple files
}
// Function represents a single profiled function with aggregated inclusive costs.
type Function struct {
Name string
File string
Costs []int64 // one entry per Profile.Events; inclusive (includes callees)
Calls []*Call // outgoing call edges
CalledBy []*Call // incoming call edges
}
// Call is a directed call edge between two functions.
type Call struct {
Caller *Function
Callee *Function
Count int64
Costs []int64
}
```
- [ ] **Verify compilation**
```bash
go build ./internal/cachegrind/...
```
Expected: no output (success)
- [ ] **Commit**
```bash
git add internal/cachegrind/model.go
git commit -m "feat: add cachegrind data model"
```
---
## Task 3: Cachegrind parser (TDD)
**Files:**
- Create: `internal/cachegrind/parser_test.go`
- Create: `internal/cachegrind/parser.go`
- [ ] **Write the failing test** (`internal/cachegrind/parser_test.go`)
```go
package cachegrind_test
import (
"strings"
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"forge.lclr.dev/AI/xdebug-mcp/internal/cachegrind"
)
const simpleFixture = `version: 1
creator: test
cmd: index.php
part: 1
positions: line
events: Time_(10ns) Memory_(bytes)
fl=(1) index.php
fn=(1) main
1 2000 1000
cfl=(1)
cfn=(2)
calls=1 0 0
2 1500 700
fl=(1)
fn=(2) query
10 1500 700
cfl=(1)
cfn=(3)
calls=2 0 0
15 500 200
fl=(1)
fn=(3) connect
20 250 100
`
func TestParseSimple(t *testing.T) {
p, err := cachegrind.Parse(strings.NewReader(simpleFixture))
require.NoError(t, err)
assert.Equal(t, "index.php", p.Cmd)
assert.Equal(t, []string{"Time_(10ns)", "Memory_(bytes)"}, p.Events)
assert.Len(t, p.Functions, 3)
main := p.ByName["main"]
require.Len(t, main, 1)
// main costs: self (2000,1000) + call to query (1500,700) = (3500,1700)
assert.Equal(t, []int64{3500, 1700}, main[0].Costs)
assert.Len(t, main[0].Calls, 1)
assert.Equal(t, int64(1), main[0].Calls[0].Count)
assert.Equal(t, "query", main[0].Calls[0].Callee.Name)
query := p.ByName["query"]
require.Len(t, query, 1)
assert.Equal(t, []int64{2000, 900}, query[0].Costs)
assert.Len(t, query[0].CalledBy, 1)
assert.Len(t, query[0].Calls, 1)
assert.Equal(t, int64(2), query[0].Calls[0].Count)
connect := p.ByName["connect"]
require.Len(t, connect, 1)
assert.Equal(t, []int64{250, 100}, connect[0].Costs)
assert.Empty(t, connect[0].Calls)
assert.Len(t, connect[0].CalledBy, 1)
}
func TestParseFile_gzip(t *testing.T) {
path := "/home/leclere/Uppler/apps/uppler1/docker/tmp/xdebug/cachegrind.out.45.gz"
p, err := cachegrind.ParseFile(path)
if err != nil {
t.Skipf("real file unavailable: %v", err)
}
assert.NotEmpty(t, p.Events)
assert.NotEmpty(t, p.Functions)
assert.NotEmpty(t, p.Cmd)
}
```
- [ ] **Run test — verify it fails**
```bash
go test ./internal/cachegrind/... -v -run TestParseSimple
```
Expected: FAIL — `cachegrind.Parse undefined`
- [ ] **Create parser.go** (`internal/cachegrind/parser.go`)
```go
package cachegrind
import (
"bufio"
"compress/gzip"
"fmt"
"io"
"os"
"strconv"
"strings"
)
// ParseFile opens a cachegrind file (plain text or gzip) and returns a Profile.
func ParseFile(path string) (*Profile, error) {
f, err := os.Open(path)
if err != nil {
return nil, fmt.Errorf("open %s: %w", path, err)
}
defer f.Close()
var r io.Reader = f
if strings.HasSuffix(path, ".gz") {
gr, gzErr := gzip.NewReader(f)
if gzErr != nil {
// fall back to plain text
if _, seekErr := f.Seek(0, io.SeekStart); seekErr != nil {
return nil, fmt.Errorf("gzip open %s: %w", path, gzErr)
}
} else {
defer gr.Close()
r = gr
}
}
return Parse(r)
}
// Parse reads cachegrind format from r and returns a Profile.
// All cost lines for a function are summed into inclusive costs (includes callees).
func Parse(r io.Reader) (*Profile, error) {
p := &Profile{ByName: make(map[string][]*Function)}
flTable := map[int]string{}
fnTable := map[int]*Function{}
currentFile := ""
var currentFn *Function
var pendingCallee *Function
pendingCallCount := int64(0)
inCallCtx := false
nEvents := 0
scanner := bufio.NewScanner(r)
scanner.Buffer(make([]byte, 4*1024*1024), 4*1024*1024)
for scanner.Scan() {
line := scanner.Text()
if line == "" || strings.HasPrefix(line, "#") {
continue
}
switch {
case strings.HasPrefix(line, "events:"):
p.Events = strings.Fields(strings.TrimPrefix(line, "events:"))
nEvents = len(p.Events)
case strings.HasPrefix(line, "cmd:"):
p.Cmd = strings.TrimSpace(strings.TrimPrefix(line, "cmd:"))
case strings.HasPrefix(line, "version:"), strings.HasPrefix(line, "creator:"),
strings.HasPrefix(line, "part:"), strings.HasPrefix(line, "positions:"),
strings.HasPrefix(line, "ob="), strings.HasPrefix(line, "totals:"),
strings.HasPrefix(line, "summary:"):
// header/summary fields — skip
case strings.HasPrefix(line, "fl="):
alias, name := parseAlias(line[3:])
if name != "" {
flTable[alias] = name
}
currentFile = flTable[alias]
inCallCtx = false
case strings.HasPrefix(line, "fn="):
alias, name := parseAlias(line[3:])
if name != "" {
fn := &Function{
Name: name,
File: currentFile,
Costs: make([]int64, nEvents),
}
fnTable[alias] = fn
p.Functions = append(p.Functions, fn)
p.ByName[name] = append(p.ByName[name], fn)
}
currentFn = fnTable[alias]
inCallCtx = false
case strings.HasPrefix(line, "cfl="):
// called file alias — not needed for P0 (already known from fn= alias)
case strings.HasPrefix(line, "cfn="):
alias, _ := parseAlias(line[4:])
pendingCallee = fnTable[alias]
case strings.HasPrefix(line, "calls="):
parts := strings.Fields(line[6:])
if len(parts) > 0 {
pendingCallCount, _ = strconv.ParseInt(parts[0], 10, 64)
}
inCallCtx = true
default:
if len(line) == 0 || line[0] < '0' || line[0] > '9' {
continue
}
costs, err := parseCostLine(line, nEvents)
if err != nil {
continue
}
if inCallCtx && currentFn != nil && pendingCallee != nil {
call := &Call{
Caller: currentFn,
Callee: pendingCallee,
Count: pendingCallCount,
Costs: costs,
}
currentFn.Calls = append(currentFn.Calls, call)
pendingCallee.CalledBy = append(pendingCallee.CalledBy, call)
pendingCallee = nil
pendingCallCount = 0
inCallCtx = false
}
if currentFn != nil {
addCosts(currentFn.Costs, costs)
}
}
}
return p, scanner.Err()
}
// parseAlias parses "(N)" or "(N) name" from the value portion of fl=/fn=.
func parseAlias(s string) (int, string) {
if !strings.HasPrefix(s, "(") {
return 0, ""
}
end := strings.Index(s, ")")
if end < 0 {
return 0, ""
}
alias, _ := strconv.Atoi(s[1:end])
name := ""
if len(s) > end+1 {
name = strings.TrimSpace(s[end+1:])
}
return alias, name
}
// parseCostLine parses "linenum cost1 cost2 ..." and returns the cost slice.
func parseCostLine(line string, nEvents int) ([]int64, error) {
parts := strings.Fields(line)
if len(parts) < 2 {
return nil, fmt.Errorf("short cost line: %q", line)
}
costs := make([]int64, nEvents)
for i := 0; i < nEvents && i+1 < len(parts); i++ {
v, err := strconv.ParseInt(parts[i+1], 10, 64)
if err != nil {
return nil, err
}
costs[i] = v
}
return costs, nil
}
func addCosts(dst, src []int64) {
for i := range src {
if i < len(dst) {
dst[i] += src[i]
}
}
}
```
- [ ] **Run test — verify it passes**
```bash
go test ./internal/cachegrind/... -v
```
Expected: PASS (both TestParseSimple and TestParseFile_gzip; the gzip test may SKIP if the file is unavailable)
- [ ] **Commit**
```bash
git add internal/cachegrind/
git commit -m "feat: add cachegrind parser with gzip support"
```
---
## Task 4: LRU cache (TDD)
**Files:**
- Create: `internal/cache/lru_test.go`
- Create: `internal/cache/lru.go`
- [ ] **Write the failing test** (`internal/cache/lru_test.go`)
```go
package cache_test
import (
"testing"
"time"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"forge.lclr.dev/AI/xdebug-mcp/internal/cache"
"forge.lclr.dev/AI/xdebug-mcp/internal/cachegrind"
)
func TestLRU_GetSet(t *testing.T) {
c := cache.New(2)
t0 := time.Now()
p := &cachegrind.Profile{Cmd: "p1"}
c.Set("/a", p, t0)
got, ok := c.Get("/a", t0)
require.True(t, ok)
assert.Equal(t, p, got)
}
func TestLRU_Eviction(t *testing.T) {
c := cache.New(2)
t0 := time.Now()
p1 := &cachegrind.Profile{Cmd: "p1"}
p2 := &cachegrind.Profile{Cmd: "p2"}
p3 := &cachegrind.Profile{Cmd: "p3"}
c.Set("/a", p1, t0)
c.Set("/b", p2, t0)
c.Get("/a", t0) // access /a → /b becomes LRU
c.Set("/c", p3, t0) // should evict /b
_, ok := c.Get("/b", t0)
assert.False(t, ok, "b should have been evicted")
got, ok := c.Get("/a", t0)
require.True(t, ok)
assert.Equal(t, p1, got)
got, ok = c.Get("/c", t0)
require.True(t, ok)
assert.Equal(t, p3, got)
}
func TestLRU_ModtimeInvalidation(t *testing.T) {
c := cache.New(2)
t1 := time.Now()
t2 := t1.Add(time.Second)
c.Set("/a", &cachegrind.Profile{Cmd: "old"}, t1)
_, ok := c.Get("/a", t2) // newer modtime → stale
assert.False(t, ok)
}
```
- [ ] **Run test — verify it fails**
```bash
go test ./internal/cache/... -v
```
Expected: FAIL — `cache.New undefined`
- [ ] **Create lru.go** (`internal/cache/lru.go`)
```go
package cache
import (
"container/list"
"sync"
"time"
"forge.lclr.dev/AI/xdebug-mcp/internal/cachegrind"
)
const DefaultCapacity = 2
type entry struct {
key string
profile *cachegrind.Profile
modTime time.Time
elem *list.Element
}
// Cache is a thread-safe LRU cache keyed by absolute file path.
type Cache struct {
mu sync.Mutex
capacity int
items map[string]*entry
order list.List
}
func New(capacity int) *Cache {
return &Cache{
capacity: capacity,
items: make(map[string]*entry),
}
}
// Get returns the cached Profile if key exists and modTime matches.
func (c *Cache) Get(key string, modTime time.Time) (*cachegrind.Profile, bool) {
c.mu.Lock()
defer c.mu.Unlock()
e, ok := c.items[key]
if !ok {
return nil, false
}
if !e.modTime.Equal(modTime) {
c.evict(e)
return nil, false
}
c.order.MoveToFront(e.elem)
return e.profile, true
}
// Set stores a Profile, evicting the least-recently-used entry if at capacity.
func (c *Cache) Set(key string, profile *cachegrind.Profile, modTime time.Time) {
c.mu.Lock()
defer c.mu.Unlock()
if e, ok := c.items[key]; ok {
c.evict(e)
}
for len(c.items) >= c.capacity {
back := c.order.Back()
if back == nil {
break
}
c.evict(back.Value.(*entry))
}
e := &entry{key: key, profile: profile, modTime: modTime}
e.elem = c.order.PushFront(e)
c.items[key] = e
}
func (c *Cache) evict(e *entry) {
c.order.Remove(e.elem)
delete(c.items, e.key)
}
```
- [ ] **Run test — verify it passes**
```bash
go test ./internal/cache/... -v
```
Expected: PASS (3 tests)
- [ ] **Commit**
```bash
git add internal/cache/
git commit -m "feat: add LRU cache for parsed profiles"
```
---
## Task 5: Shared tool helpers
**Files:**
- Create: `internal/tools/shared.go`
- [ ] **Create shared.go** (`internal/tools/shared.go`)
```go
package tools
import (
"fmt"
"os"
"path/filepath"
"sort"
"strings"
"forge.lclr.dev/AI/xdebug-mcp/internal/cache"
"forge.lclr.dev/AI/xdebug-mcp/internal/cachegrind"
)
// loadProfile returns a parsed Profile from cache or by parsing the file.
func loadProfile(filePath string, c *cache.Cache) (*cachegrind.Profile, error) {
abs, err := filepath.Abs(filePath)
if err != nil {
return nil, fmt.Errorf("resolve path %s: %w", filePath, err)
}
info, err := os.Stat(abs)
if err != nil {
return nil, fmt.Errorf("file not found: %s", abs)
}
if p, ok := c.Get(abs, info.ModTime()); ok {
return p, nil
}
p, err := cachegrind.ParseFile(abs)
if err != nil {
return nil, err
}
c.Set(abs, p, info.ModTime())
return p, nil
}
// findFunctions returns functions matching name (exact first, then contains).
// Returns a non-empty errMsg if nothing is found.
func findFunctions(p *cachegrind.Profile, name string) ([]*cachegrind.Function, string) {
if fns, ok := p.ByName[name]; ok {
return fns, ""
}
var matches []*cachegrind.Function
for _, fn := range p.Functions {
if strings.Contains(fn.Name, name) {
matches = append(matches, fn)
}
}
if len(matches) == 0 {
return nil, fmt.Sprintf("function %q not found in profile (no exact or contains match)", name)
}
return matches, ""
}
// sortedByTime returns a copy of fns sorted by Costs[0] descending.
func sortedByTime(fns []*cachegrind.Function) []*cachegrind.Function {
sorted := make([]*cachegrind.Function, len(fns))
copy(sorted, fns)
sort.Slice(sorted, func(i, j int) bool {
ci, cj := int64(0), int64(0)
if len(sorted[i].Costs) > 0 {
ci = sorted[i].Costs[0]
}
if len(sorted[j].Costs) > 0 {
cj = sorted[j].Costs[0]
}
return ci > cj
})
return sorted
}
// formatCosts formats a cost slice as "Event=value Event=value".
func formatCosts(costs []int64, events []string) string {
parts := make([]string, 0, len(events))
for i, ev := range events {
if i < len(costs) {
parts = append(parts, fmt.Sprintf("%s=%d", ev, costs[i]))
}
}
return strings.Join(parts, " ")
}
```
- [ ] **Build to verify**
```bash
go build ./internal/tools/...
```
Expected: success
- [ ] **Commit**
```bash
git add internal/tools/shared.go
git commit -m "feat: add shared tool helpers"
```
---
## Task 6: analyze_profile tool (TDD)
**Files:**
- Create: `internal/tools/tools_test.go`
- Create: `internal/tools/analyze.go`
- [ ] **Write the failing test** — test helper + analyze test only (`internal/tools/tools_test.go`)
```go
package tools_test
import (
"strings"
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"forge.lclr.dev/AI/xdebug-mcp/internal/cachegrind"
"forge.lclr.dev/AI/xdebug-mcp/internal/tools"
)
func makeTestProfile() *cachegrind.Profile {
main := &cachegrind.Function{Name: "main", File: "index.php", Costs: []int64{3500, 1700}}
query := &cachegrind.Function{Name: "query", File: "index.php", Costs: []int64{2000, 900}}
connect := &cachegrind.Function{Name: "connect", File: "index.php", Costs: []int64{250, 100}}
call1 := &cachegrind.Call{Caller: main, Callee: query, Count: 1, Costs: []int64{1500, 700}}
call2 := &cachegrind.Call{Caller: query, Callee: connect, Count: 2, Costs: []int64{500, 200}}
main.Calls = []*cachegrind.Call{call1}
query.CalledBy = []*cachegrind.Call{call1}
query.Calls = []*cachegrind.Call{call2}
connect.CalledBy = []*cachegrind.Call{call2}
return &cachegrind.Profile{
Cmd: "index.php",
Events: []string{"Time_(10ns)", "Memory_(bytes)"},
Functions: []*cachegrind.Function{main, query, connect},
ByName: map[string][]*cachegrind.Function{
"main": {main},
"query": {query},
"connect": {connect},
},
}
}
func TestAnalyze_TopN(t *testing.T) {
p := makeTestProfile()
result := tools.Analyze(p, 3)
assert.Contains(t, result, "index.php")
assert.Contains(t, result, "Functions: 3 total")
assert.Contains(t, result, "main")
assert.Contains(t, result, "query")
assert.Contains(t, result, "connect")
// main must appear before query (higher cost)
assert.Less(t, strings.Index(result, "main"), strings.Index(result, "query"))
}
func TestAnalyze_TopNLimited(t *testing.T) {
p := makeTestProfile()
result := tools.Analyze(p, 1)
assert.Contains(t, result, "main")
assert.NotContains(t, result, "query") // only top 1
}
```
- [ ] **Run test — verify it fails**
```bash
go test ./internal/tools/... -v -run TestAnalyze
```
Expected: FAIL — `tools.Analyze undefined`
- [ ] **Create analyze.go** (`internal/tools/analyze.go`)
```go
package tools
import (
"context"
"fmt"
"strings"
"github.com/mark3labs/mcp-go/mcp"
"github.com/mark3labs/mcp-go/server"
"forge.lclr.dev/AI/xdebug-mcp/internal/cache"
"forge.lclr.dev/AI/xdebug-mcp/internal/cachegrind"
)
// AnalyzeTool returns the MCP tool definition for analyze_profile.
func AnalyzeTool() mcp.Tool {
return mcp.NewTool("analyze_profile",
mcp.WithDescription("Analyze an Xdebug cachegrind profiling file. Returns global stats and top N functions sorted by inclusive time cost."),
mcp.WithString("file_path",
mcp.Required(),
mcp.Description("Absolute or relative path to the cachegrind file (.gz or plain text)"),
),
mcp.WithNumber("top_n",
mcp.Description("Number of top functions to return (default: 20)"),
),
)
}
// AnalyzeHandler returns the MCP handler for analyze_profile.
func AnalyzeHandler(c *cache.Cache) server.ToolHandlerFunc {
return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
filePath, ok := req.Params.Arguments["file_path"].(string)
if !ok || filePath == "" {
return mcp.NewToolResultError("file_path is required"), nil
}
topN := 20
if n, ok := req.Params.Arguments["top_n"].(float64); ok && n > 0 {
topN = int(n)
}
p, err := loadProfile(filePath, c)
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
return mcp.NewToolResultText(Analyze(p, topN)), nil
}
}
// Analyze formats the top-N analysis of p. Exported for testing.
func Analyze(p *cachegrind.Profile, topN int) string {
sorted := sortedByTime(p.Functions)
if topN > len(sorted) {
topN = len(sorted)
}
var sb strings.Builder
fmt.Fprintf(&sb, "Command: %s\n", p.Cmd)
fmt.Fprintf(&sb, "Events: %s\n", strings.Join(p.Events, ", "))
fmt.Fprintf(&sb, "Functions: %d total\n\n", len(p.Functions))
peak := int64(0)
if len(sorted) > 0 && len(sorted[0].Costs) > 0 {
peak = sorted[0].Costs[0]
}
if len(p.Events) > 0 {
fmt.Fprintf(&sb, "Top %d functions by %s:\n", topN, p.Events[0])
}
for i, fn := range sorted[:topN] {
pct := ""
if peak > 0 && len(fn.Costs) > 0 {
pct = fmt.Sprintf(" (%.1f%% of peak)", float64(fn.Costs[0])/float64(peak)*100)
}
fmt.Fprintf(&sb, " %3d. %-60s %s%s\n", i+1, fn.Name, formatCosts(fn.Costs, p.Events), pct)
fmt.Fprintf(&sb, " %s\n", fn.File)
}
return sb.String()
}
```
- [ ] **Run test — verify it passes**
```bash
go test ./internal/tools/... -v -run TestAnalyze
```
Expected: PASS
- [ ] **Commit**
```bash
git add internal/tools/analyze.go internal/tools/tools_test.go
git commit -m "feat: add analyze_profile tool"
```
---
## Task 7: get_callers and get_callees tools (TDD)
**Files:**
- Modify: `internal/tools/tools_test.go`
- Create: `internal/tools/callers.go`
- Create: `internal/tools/callees.go`
- [ ] **Add tests to tools_test.go** (append to the existing file)
```go
func TestCallers_Found(t *testing.T) {
p := makeTestProfile()
result := tools.Callers(p, "query", 10)
assert.Contains(t, result, "main")
assert.Contains(t, result, "calls=1")
require.NotContains(t, result, "not found")
}
func TestCallers_ContainsFallback(t *testing.T) {
p := makeTestProfile()
// "uer" is a substring of "query"
result := tools.Callers(p, "uer", 10)
assert.Contains(t, result, "main")
}
func TestCallers_NotFound(t *testing.T) {
p := makeTestProfile()
result := tools.Callers(p, "nonexistent_xyz", 10)
assert.Contains(t, result, "not found")
}
func TestCallees_Found(t *testing.T) {
p := makeTestProfile()
result := tools.Callees(p, "query", 10)
assert.Contains(t, result, "connect")
assert.Contains(t, result, "calls=2")
}
func TestCallees_NotFound(t *testing.T) {
p := makeTestProfile()
result := tools.Callees(p, "connect", 10) // connect has no callees
assert.Contains(t, result, "no outgoing calls")
}
```
- [ ] **Run tests — verify they fail**
```bash
go test ./internal/tools/... -v -run "TestCallers|TestCallees"
```
Expected: FAIL — `tools.Callers undefined`, `tools.Callees undefined`
- [ ] **Create callers.go** (`internal/tools/callers.go`)
```go
package tools
import (
"context"
"fmt"
"strings"
"github.com/mark3labs/mcp-go/mcp"
"github.com/mark3labs/mcp-go/server"
"forge.lclr.dev/AI/xdebug-mcp/internal/cache"
"forge.lclr.dev/AI/xdebug-mcp/internal/cachegrind"
)
// CallersTool returns the MCP tool definition for get_callers.
func CallersTool() mcp.Tool {
return mcp.NewTool("get_callers",
mcp.WithDescription("List functions that call a given function in an Xdebug profiling file, sorted by call cost descending."),
mcp.WithString("file_path",
mcp.Required(),
mcp.Description("Absolute or relative path to the cachegrind file"),
),
mcp.WithString("function_name",
mcp.Required(),
mcp.Description("Exact function name or substring to search for"),
),
mcp.WithNumber("top_n",
mcp.Description("Maximum number of callers to return (default: 10)"),
),
)
}
// CallersHandler returns the MCP handler for get_callers.
func CallersHandler(c *cache.Cache) server.ToolHandlerFunc {
return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
filePath, ok := req.Params.Arguments["file_path"].(string)
if !ok || filePath == "" {
return mcp.NewToolResultError("file_path is required"), nil
}
name, ok := req.Params.Arguments["function_name"].(string)
if !ok || name == "" {
return mcp.NewToolResultError("function_name is required"), nil
}
topN := 10
if n, ok := req.Params.Arguments["top_n"].(float64); ok && n > 0 {
topN = int(n)
}
p, err := loadProfile(filePath, c)
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
return mcp.NewToolResultText(Callers(p, name, topN)), nil
}
}
// Callers formats the callers of name in p. Exported for testing.
func Callers(p *cachegrind.Profile, name string, topN int) string {
fns, errMsg := findFunctions(p, name)
if errMsg != "" {
return errMsg
}
var sb strings.Builder
for _, fn := range fns {
fmt.Fprintf(&sb, "Callers of %q [%s]\n", fn.Name, fn.File)
if len(fn.CalledBy) == 0 {
fmt.Fprintf(&sb, " no incoming calls recorded\n\n")
continue
}
callers := sortedCalls(fn.CalledBy)
if topN < len(callers) {
callers = callers[:topN]
}
fmt.Fprintf(&sb, " called by %d function(s):\n\n", len(fn.CalledBy))
for i, call := range callers {
fmt.Fprintf(&sb, " %3d. %-60s calls=%d %s\n",
i+1, call.Caller.Name, call.Count, formatCosts(call.Costs, p.Events))
fmt.Fprintf(&sb, " %s\n", call.Caller.File)
}
fmt.Fprintln(&sb)
}
return sb.String()
}
// sortedCalls returns a copy of calls sorted by Costs[0] descending.
func sortedCalls(calls []*cachegrind.Call) []*cachegrind.Call {
out := make([]*cachegrind.Call, len(calls))
copy(out, calls)
sortCallSlice(out)
return out
}
func sortCallSlice(calls []*cachegrind.Call) {
for i := 1; i < len(calls); i++ {
for j := i; j > 0; j-- {
ci, cj := int64(0), int64(0)
if len(calls[j].Costs) > 0 {
ci = calls[j].Costs[0]
}
if len(calls[j-1].Costs) > 0 {
cj = calls[j-1].Costs[0]
}
if ci > cj {
calls[j], calls[j-1] = calls[j-1], calls[j]
} else {
break
}
}
}
}
```
- [ ] **Create callees.go** (`internal/tools/callees.go`)
```go
package tools
import (
"context"
"fmt"
"strings"
"github.com/mark3labs/mcp-go/mcp"
"github.com/mark3labs/mcp-go/server"
"forge.lclr.dev/AI/xdebug-mcp/internal/cache"
"forge.lclr.dev/AI/xdebug-mcp/internal/cachegrind"
)
// CalleesTool returns the MCP tool definition for get_callees.
func CalleesTool() mcp.Tool {
return mcp.NewTool("get_callees",
mcp.WithDescription("List functions called by a given function in an Xdebug profiling file, sorted by call cost descending."),
mcp.WithString("file_path",
mcp.Required(),
mcp.Description("Absolute or relative path to the cachegrind file"),
),
mcp.WithString("function_name",
mcp.Required(),
mcp.Description("Exact function name or substring to search for"),
),
mcp.WithNumber("top_n",
mcp.Description("Maximum number of callees to return (default: 10)"),
),
)
}
// CalleesHandler returns the MCP handler for get_callees.
func CalleesHandler(c *cache.Cache) server.ToolHandlerFunc {
return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
filePath, ok := req.Params.Arguments["file_path"].(string)
if !ok || filePath == "" {
return mcp.NewToolResultError("file_path is required"), nil
}
name, ok := req.Params.Arguments["function_name"].(string)
if !ok || name == "" {
return mcp.NewToolResultError("function_name is required"), nil
}
topN := 10
if n, ok := req.Params.Arguments["top_n"].(float64); ok && n > 0 {
topN = int(n)
}
p, err := loadProfile(filePath, c)
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
return mcp.NewToolResultText(Callees(p, name, topN)), nil
}
}
// Callees formats the callees of name in p. Exported for testing.
func Callees(p *cachegrind.Profile, name string, topN int) string {
fns, errMsg := findFunctions(p, name)
if errMsg != "" {
return errMsg
}
var sb strings.Builder
for _, fn := range fns {
fmt.Fprintf(&sb, "Callees of %q [%s]\n", fn.Name, fn.File)
if len(fn.Calls) == 0 {
fmt.Fprintf(&sb, " no outgoing calls recorded\n\n")
continue
}
callees := sortedCalls(fn.Calls)
if topN < len(callees) {
callees = callees[:topN]
}
fmt.Fprintf(&sb, " calls %d function(s):\n\n", len(fn.Calls))
for i, call := range callees {
fmt.Fprintf(&sb, " %3d. %-60s calls=%d %s\n",
i+1, call.Callee.Name, call.Count, formatCosts(call.Costs, p.Events))
fmt.Fprintf(&sb, " %s\n", call.Callee.File)
}
fmt.Fprintln(&sb)
}
return sb.String()
}
```
- [ ] **Run all tools tests — verify they pass**
```bash
go test ./internal/tools/... -v
```
Expected: PASS (all 7 tests)
- [ ] **Commit**
```bash
git add internal/tools/
git commit -m "feat: add get_callers and get_callees tools"
```
---
## Task 8: Wiring — app.go and main.go
**Files:**
- Create: `internal/app/app.go`
- Create: `cmd/xdebug-mcp/main.go`
- [ ] **Create app.go** (`internal/app/app.go`)
```go
package app
import (
"context"
"github.com/mark3labs/mcp-go/server"
"forge.lclr.dev/AI/mcp-framework/bootstrap"
"forge.lclr.dev/AI/xdebug-mcp/internal/cache"
"forge.lclr.dev/AI/xdebug-mcp/internal/tools"
"forge.lclr.dev/AI/xdebug-mcp/mcpgen"
)
func Run(ctx context.Context, args []string, version string) error {
c := cache.New(cache.DefaultCapacity)
return bootstrap.Run(ctx, bootstrap.Options{
BinaryName: mcpgen.BinaryName,
Description: mcpgen.DefaultDescription,
Version: version,
Args: args,
Hooks: bootstrap.Hooks{
MCP: func(ctx context.Context, inv bootstrap.Invocation) error {
return runMCP(c, version)
},
},
})
}
func runMCP(c *cache.Cache, version string) error {
s := server.NewMCPServer(mcpgen.BinaryName, version)
s.AddTool(tools.AnalyzeTool(), tools.AnalyzeHandler(c))
s.AddTool(tools.CallersTool(), tools.CallersHandler(c))
s.AddTool(tools.CalleesTool(), tools.CalleesHandler(c))
return server.ServeStdio(s)
}
```
- [ ] **Create main.go** (`cmd/xdebug-mcp/main.go`)
```go
package main
import (
"context"
"log"
"os"
"forge.lclr.dev/AI/xdebug-mcp/internal/app"
)
var version = "dev"
func main() {
if err := app.Run(context.Background(), os.Args[1:], version); err != nil {
log.Fatal(err)
}
}
```
- [ ] **Build the binary**
```bash
go build ./cmd/xdebug-mcp/
```
Expected: binary `xdebug-mcp` created in current directory, no errors
- [ ] **Verify help output**
```bash
./xdebug-mcp help
```
Expected: usage output listing the `mcp` subcommand
- [ ] **Commit**
```bash
git add internal/app/app.go cmd/xdebug-mcp/main.go
git commit -m "feat: wire MCP server with bootstrap CLI"
```
---
## Task 9: Integration smoke test
- [ ] **Run tools/list via MCP protocol**
```bash
echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' | ./xdebug-mcp mcp
```
Expected: JSON response with `serverInfo` containing `name: "xdebug-mcp"`
- [ ] **Test analyze_profile on a real file**
```bash
echo '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"analyze_profile","arguments":{"file_path":"/home/leclere/Uppler/apps/uppler1/docker/tmp/xdebug/cachegrind.out.45.gz","top_n":5}}}' | ./xdebug-mcp mcp
```
Expected: JSON response with `content[0].text` containing top 5 PHP functions with costs
- [ ] **Commit binary to .gitignore and finalize**
```bash
echo "xdebug-mcp" >> .gitignore
git add .gitignore
git commit -m "chore: ignore built binary"
```
---
## Notes for the implementer
- **mcpgen constants**: After running `mcp-framework generate`, inspect `mcpgen/metadata.go` to confirm the exact names of `BinaryName` and `DefaultDescription`. Adjust `app.go` if the names differ.
- **mark3labs/mcp-go API**: Parameter extraction uses `req.Params.Arguments["key"].(type)` — JSON numbers arrive as `float64`. If `mcp.WithNumber` is not available in the installed version, use `mcp.WithString` and parse manually.
- **MCP protocol handshake**: `server.ServeStdio` handles the `initialize` / `initialized` handshake automatically. Tools are only callable after the handshake.
- **Large files**: The first call to `analyze_profile` on a 325 MB uncompressed file takes several seconds to parse. Subsequent calls on the same file hit the LRU cache and are instant.
Copy permalink