feat(mcp): improve project context awareness in MCP tool descriptions (#274)

* feat(mcp): improve project context awareness in MCP tool descriptions

* feat(hookdeck): add ProjectOrg to Client for MCP context

ProjectName remains the short project name; ProjectOrg holds the
organization label for telemetry clones and MCP meta. WithTelemetry
copies both fields.

Made-with: Cursor

* feat(mcp): envelope meta with active_project_org and short name

JSONResultEnvelope takes separate org and short name; active_project_org
is omitted when empty. Add fillProjectDisplayNameIfNeeded before handlers
to resolve org/name from ListProjects when only project id is cached.

Made-with: Cursor

* feat(mcp): use JSONResultEnvelopeForClient on resource tools

Wire list/get and login/projects handlers so meta includes split org and
short project name from the shared client.

Made-with: Cursor

* docs(mcp): help and tests for active_project_org meta

Update hookdeck_help copy, tool descriptions, and assertions for the
split org / short name fields in meta and current-project display.

Made-with: Cursor

* docs(agents): require GPG-signed commits for maintainers

Document that commits must be signed and that agents should use full
permissions when gpg-agent is otherwise unreachable.

Made-with: Cursor

---------

Co-authored-by: leggetter <leggetter@users.noreply.github.com>
Co-authored-by: Phil Leggetter <phil@leggetter.co.uk>

Author: github-actions[bot]

AGENTS.md

@@ -249,6 +249,12 @@ Commands that need network (e.g. `git push`, `gh pr create`, `npm install`) or f
 
 **Prefer requesting elevated permissions** (e.g. `required_permissions: ["all"]` or `["network"]`) and asking the user to approve so the agent can retry the command. Do not default to prompting the user to run commands themselves when elevation is available. Only fall back to copy-pasteable commands when elevated permissions are not an option.
 
+### Git commits (GPG)
+
+**Always use GPG-signed commits** (`git commit -S`, or `commit.gpgsign=true` in git config). **Do not** use `--no-gpg-sign` to bypass signing.
+
+In restricted environments, signing may fail with errors like “No agent running” or “Operation not permitted” on `~/.gnupg`. **Re-run the commit with full permissions** so `gpg-agent` is reachable, or sign from a normal local terminal. Unsigned commits should not be pushed as a shortcut.
+
 ### Linting and Formatting
 ```bash
 # Format code

pkg/gateway/mcp/project_display.go

@@ -0,0 +1,32 @@
+package mcp
+
+import (
+	"github.com/hookdeck/hookdeck-cli/pkg/hookdeck"
+	"github.com/hookdeck/hookdeck-cli/pkg/project"
+)
+
+// fillProjectDisplayNameIfNeeded sets client.ProjectOrg and client.ProjectName from
+// ListProjects when the client has an API key and project id but no cached org/name
+// (typical after loading profile from disk). Fails silently on API errors.
+// Stdio MCP invokes tools sequentially, so this is safe without locking.
+func fillProjectDisplayNameIfNeeded(client *hookdeck.Client) {
+	if client == nil || client.APIKey == "" || client.ProjectID == "" {
+		return
+	}
+	if client.ProjectName != "" || client.ProjectOrg != "" {
+		return
+	}
+	projects, err := client.ListProjects()
+	if err != nil {
+		return
+	}
+	items := project.NormalizeProjects(projects, client.ProjectID)
+	for i := range items {
+		if items[i].Id != client.ProjectID {
+			continue
+		}
+		client.ProjectOrg = items[i].Org
+		client.ProjectName = items[i].Project
+		return
+	}
+}

pkg/gateway/mcp/project_display_test.go

@@ -0,0 +1,42 @@
+package mcp
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+
+	"github.com/hookdeck/hookdeck-cli/pkg/hookdeck"
+	"github.com/stretchr/testify/require"
+)
+
+func TestFillProjectDisplayNameIfNeeded_SetsNameFromAPI(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/2025-07-01/teams" {
+			http.NotFound(w, r)
+			return
+		}
+		_ = json.NewEncoder(w).Encode([]map[string]any{
+			{"id": "proj_x", "name": "[Acme] production", "mode": "console"},
+		})
+	}))
+	t.Cleanup(srv.Close)
+
+	u, err := url.Parse(srv.URL)
+	require.NoError(t, err)
+	client := &hookdeck.Client{
+		BaseURL:   u,
+		APIKey:    "k",
+		ProjectID: "proj_x",
+	}
+	fillProjectDisplayNameIfNeeded(client)
+	require.Equal(t, "Acme", client.ProjectOrg)
+	require.Equal(t, "production", client.ProjectName)
+}
+
+func TestFillProjectDisplayNameIfNeeded_NoOpWhenNameSet(t *testing.T) {
+	client := &hookdeck.Client{ProjectID: "p", ProjectName: "already"}
+	fillProjectDisplayNameIfNeeded(client)
+	require.Equal(t, "already", client.ProjectName)
+}

pkg/gateway/mcp/response.go

@@ -4,11 +4,67 @@ import (
 	"encoding/json"
 
 	mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"github.com/hookdeck/hookdeck-cli/pkg/hookdeck"
 )
 
+// JSONResultEnvelope returns a CallToolResult whose text body is always:
+//
+//	{"data":<payload>,"meta":{...}}
+//
+// When projectID is non-empty, meta always includes active_project_id and
+// active_project_name (short name; may be ""). active_project_org is included
+// when projectOrg is non-empty. When projectID is empty, meta is {}.
+func JSONResultEnvelope(data any, projectID, projectOrg, projectShortName string) (*mcpsdk.CallToolResult, error) {
+	dataBytes, err := json.Marshal(data)
+	if err != nil {
+		return nil, err
+	}
+	var metaBytes []byte
+	if projectID == "" {
+		metaBytes = []byte("{}")
+	} else {
+		m := map[string]string{
+			"active_project_id":   projectID,
+			"active_project_name": projectShortName,
+		}
+		if projectOrg != "" {
+			m["active_project_org"] = projectOrg
+		}
+		metaBytes, err = json.Marshal(m)
+		if err != nil {
+			return nil, err
+		}
+	}
+	env := struct {
+		Data json.RawMessage `json:"data"`
+		Meta json.RawMessage `json:"meta"`
+	}{
+		Data: dataBytes,
+		Meta: metaBytes,
+	}
+	out, err := json.Marshal(env)
+	if err != nil {
+		return nil, err
+	}
+	return &mcpsdk.CallToolResult{
+		Content: []mcpsdk.Content{
+			&mcpsdk.TextContent{Text: string(out)},
+		},
+	}, nil
+}
+
+// JSONResultEnvelopeForClient wraps data using the client's project id, org, and short name.
+func JSONResultEnvelopeForClient(data any, c *hookdeck.Client) (*mcpsdk.CallToolResult, error) {
+	if c == nil {
+		return JSONResultEnvelope(data, "", "", "")
+	}
+	return JSONResultEnvelope(data, c.ProjectID, c.ProjectOrg, c.ProjectName)
+}
+
 // JSONResult creates a CallToolResult containing the JSON-encoded value as
-// text content. This is the standard way to return structured data from a
-// tool handler.
+// text content. Prefer JSONResultEnvelope for Hookdeck MCP tools so responses
+// follow the standard data/meta shape.
 func JSONResult(v any) (*mcpsdk.CallToolResult, error) {
 	data, err := json.Marshal(v)
 	if err != nil {

pkg/gateway/mcp/response_test.go

@@ -0,0 +1,91 @@
+package mcp
+
+import (
+	"encoding/json"
+	"testing"
+
+	mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/stretchr/testify/require"
+)
+
+func firstText(t *testing.T, res *mcpsdk.CallToolResult) string {
+	t.Helper()
+	require.NotEmpty(t, res.Content)
+	tc, ok := res.Content[0].(*mcpsdk.TextContent)
+	require.True(t, ok, "expected TextContent, got %T", res.Content[0])
+	return tc.Text
+}
+
+func TestJSONResultEnvelope_NoProject_MetaEmptyObject(t *testing.T) {
+	res, err := JSONResultEnvelope(map[string]any{"items": []int{1}}, "", "", "")
+	require.NoError(t, err)
+	text := firstText(t, res)
+	var root map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal([]byte(text), &root))
+	require.Contains(t, root, "data")
+	require.Contains(t, root, "meta")
+	var inner map[string]any
+	require.NoError(t, json.Unmarshal(root["data"], &inner))
+	items := inner["items"].([]any)
+	require.Equal(t, float64(1), items[0])
+	var meta map[string]any
+	require.NoError(t, json.Unmarshal(root["meta"], &meta))
+	require.NotContains(t, meta, "active_project_id")
+	require.NotContains(t, meta, "active_project_name")
+	require.NotContains(t, meta, "active_project_org")
+}
+
+func TestJSONResultEnvelope_WithProject_FlatMetaFields(t *testing.T) {
+	res, err := JSONResultEnvelope(
+		map[string]any{"count": 2},
+		"tm_Mcf7DGlOQmds",
+		"Demos",
+		"trigger-dev-github",
+	)
+	require.NoError(t, err)
+	var root map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal([]byte(firstText(t, res)), &root))
+	var dataObj struct {
+		Count int `json:"count"`
+	}
+	require.NoError(t, json.Unmarshal(root["data"], &dataObj))
+	require.Equal(t, 2, dataObj.Count)
+
+	var meta struct {
+		ActiveProjectID   string `json:"active_project_id"`
+		ActiveProjectOrg  string `json:"active_project_org"`
+		ActiveProjectName string `json:"active_project_name"`
+	}
+	require.NoError(t, json.Unmarshal(root["meta"], &meta))
+	require.Equal(t, "tm_Mcf7DGlOQmds", meta.ActiveProjectID)
+	require.Equal(t, "Demos", meta.ActiveProjectOrg)
+	require.Equal(t, "trigger-dev-github", meta.ActiveProjectName)
+}
+
+func TestJSONResultEnvelope_DataCanBeArray(t *testing.T) {
+	res, err := JSONResultEnvelope([]int{1, 2}, "proj_x", "", "Name")
+	require.NoError(t, err)
+	var root map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal([]byte(firstText(t, res)), &root))
+	var arr []int
+	require.NoError(t, json.Unmarshal(root["data"], &arr))
+	require.Equal(t, []int{1, 2}, arr)
+	var meta map[string]any
+	require.NoError(t, json.Unmarshal(root["meta"], &meta))
+	require.Equal(t, "proj_x", meta["active_project_id"])
+	require.Equal(t, "Name", meta["active_project_name"])
+	require.NotContains(t, meta, "active_project_org")
+}
+
+func TestJSONResultEnvelope_IDOnly_IncludesEmptyName(t *testing.T) {
+	res, err := JSONResultEnvelope(map[string]int{"n": 1}, "proj_only", "", "")
+	require.NoError(t, err)
+	var root map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal([]byte(firstText(t, res)), &root))
+	var meta map[string]any
+	require.NoError(t, json.Unmarshal(root["meta"], &meta))
+	require.Equal(t, "proj_only", meta["active_project_id"])
+	require.Contains(t, meta, "active_project_name")
+	require.Equal(t, "", meta["active_project_name"])
+	require.NotContains(t, meta, "active_project_org")
+}

pkg/gateway/mcp/server.go

@@ -105,6 +105,8 @@ func (s *Server) wrapWithTelemetry(toolName string, handler mcpsdk.ToolHandler)
 		}
 		defer func() { s.client.Telemetry = nil }()
 
+		fillProjectDisplayNameIfNeeded(s.client)
+
 		return handler(ctx, req)
 	}
 }

pkg/gateway/mcp/server_test.go

@@ -374,7 +374,11 @@ func TestConnectionsGet_Success(t *testing.T) {
 
 	result := callTool(t, session, "hookdeck_connections", map[string]any{"action": "get", "id": "web_conn1"})
 	assert.False(t, result.IsError)
-	assert.Contains(t, textContent(t, result), "web_conn1")
+	text := textContent(t, result)
+	assert.Contains(t, text, "web_conn1")
+	assert.Contains(t, text, `"data"`)
+	assert.Contains(t, text, `"meta"`)
+	assert.Contains(t, text, `"active_project_id"`)
 }
 
 func TestConnectionsGet_MissingID(t *testing.T) {
@@ -817,10 +821,15 @@ func TestProjectsList_Success(t *testing.T) {
 	result := callTool(t, session, "hookdeck_projects", map[string]any{"action": "list"})
 	assert.False(t, result.IsError)
 	text := textContent(t, result)
+	assert.Contains(t, text, `"data"`)
+	assert.Contains(t, text, `"meta"`)
+	assert.Contains(t, text, `"projects"`)
 	assert.Contains(t, text, "Production")
 	assert.Contains(t, text, "Staging")
 	// Current project should be marked
 	assert.Contains(t, text, "proj_test123")
+	// newTestClient sets ProjectID — scope lives in meta.active_project_*
+	assert.Contains(t, text, `"active_project_id"`)
 }
 
 func TestProjectsUse_Success(t *testing.T) {
@@ -839,6 +848,7 @@ func TestProjectsUse_Success(t *testing.T) {
 	assert.Contains(t, text, "proj_new")
 	assert.Contains(t, text, "Staging")
 	assert.Contains(t, text, "ok")
+	assert.Contains(t, text, `"active_project_id"`)
 }
 
 func TestProjectsUse_MissingProjectID(t *testing.T) {

pkg/gateway/mcp/tool_attempts.go

@@ -45,7 +45,7 @@ func attemptsList(ctx context.Context, client *hookdeck.Client, in input) (*mcps
 	if err != nil {
 		return ErrorResult(TranslateAPIError(err)), nil
 	}
-	return JSONResult(result)
+	return JSONResultEnvelopeForClient(result, client)
 }
 
 func attemptsGet(ctx context.Context, client *hookdeck.Client, in input) (*mcpsdk.CallToolResult, error) {
@@ -57,5 +57,5 @@ func attemptsGet(ctx context.Context, client *hookdeck.Client, in input) (*mcpsd
 	if err != nil {
 		return ErrorResult(TranslateAPIError(err)), nil
 	}
-	return JSONResult(attempt)
+	return JSONResultEnvelopeForClient(attempt, client)
 }

pkg/gateway/mcp/tool_connections.go

@@ -55,7 +55,7 @@ func connectionsList(ctx context.Context, client *hookdeck.Client, in input) (*m
 	if err != nil {
 		return ErrorResult(TranslateAPIError(err)), nil
 	}
-	return JSONResult(result)
+	return JSONResultEnvelopeForClient(result, client)
 }
 
 func connectionsGet(ctx context.Context, client *hookdeck.Client, in input) (*mcpsdk.CallToolResult, error) {
@@ -67,7 +67,7 @@ func connectionsGet(ctx context.Context, client *hookdeck.Client, in input) (*mc
 	if err != nil {
 		return ErrorResult(TranslateAPIError(err)), nil
 	}
-	return JSONResult(conn)
+	return JSONResultEnvelopeForClient(conn, client)
 }
 
 func connectionsPause(ctx context.Context, client *hookdeck.Client, in input) (*mcpsdk.CallToolResult, error) {
@@ -79,7 +79,7 @@ func connectionsPause(ctx context.Context, client *hookdeck.Client, in input) (*
 	if err != nil {
 		return ErrorResult(TranslateAPIError(err)), nil
 	}
-	return JSONResult(conn)
+	return JSONResultEnvelopeForClient(conn, client)
 }
 
 func connectionsUnpause(ctx context.Context, client *hookdeck.Client, in input) (*mcpsdk.CallToolResult, error) {
@@ -91,5 +91,5 @@ func connectionsUnpause(ctx context.Context, client *hookdeck.Client, in input)
 	if err != nil {
 		return ErrorResult(TranslateAPIError(err)), nil
 	}
-	return JSONResult(conn)
+	return JSONResultEnvelopeForClient(conn, client)
 }

pkg/gateway/mcp/tool_destinations.go

@@ -43,7 +43,7 @@ func destinationsList(ctx context.Context, client *hookdeck.Client, in input) (*
 	if err != nil {
 		return ErrorResult(TranslateAPIError(err)), nil
 	}
-	return JSONResult(result)
+	return JSONResultEnvelopeForClient(result, client)
 }
 
 func destinationsGet(ctx context.Context, client *hookdeck.Client, in input) (*mcpsdk.CallToolResult, error) {
@@ -55,5 +55,5 @@ func destinationsGet(ctx context.Context, client *hookdeck.Client, in input) (*m
 	if err != nil {
 		return ErrorResult(TranslateAPIError(err)), nil
 	}
-	return JSONResult(dest)
+	return JSONResultEnvelopeForClient(dest, client)
 }