webctx 0.2.5 → 0.2.7

package/pkg/origo/server.go

@@ -3,6 +3,7 @@
 package origo
 
 import (
+	"bytes"
 	"context"
 	"crypto/sha256"
 	"crypto/subtle"
@@ -12,6 +13,7 @@ import (
 	"strings"
 
 	"github.com/amxv/webctx/pkg/retrieval"
+	"github.com/google/jsonschema-go/jsonschema"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
@@ -34,58 +36,132 @@ func makeServer() *mcp.Server {
 	}, func(_ context.Context, _ *mcp.CallToolRequest, input readLinkInput) (*mcp.CallToolResult, any, error) {
 		result, err := retrieval.ReadLinkFocused(input.URL, input.Question)
 		if err != nil {
-			return nil, nil, err
+			code := "read_failed"
+			if strings.Contains(err.Error(), "absolute HTTP(S)") || strings.Contains(err.Error(), "readable URL") {
+				code = "invalid_url"
+			}
+			return dataMCPResult(nil, &retrieval.DataError{Code: code, Message: err.Error()})
 		}
 		return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: result}}}, nil, nil
 	})
-	mcp.AddTool(s, &mcp.Tool{
+	s.AddTool(&mcp.Tool{
 		Name:        "map_site",
 		Title:       "Map site",
-		Description: "Discover URLs on a site using Firecrawl's sitemap-based map API. Does not perform web search.",
+		Description: "Discover website pages in bounded, paginated groups (30 by default). Filter by topic, path prefix and language (en by default, all for translations). Returns structured titles, descriptions, counts, and copy-ready next-page arguments.",
 		Annotations: &mcp.ToolAnnotations{ReadOnlyHint: true},
-	}, func(_ context.Context, _ *mcp.CallToolRequest, input linkInput) (*mcp.CallToolResult, any, error) {
-		result, err := retrieval.MapSite(input.URL)
-		if err != nil {
-			return nil, nil, err
-		}
-		return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: result}}}, nil, nil
-	})
-	mcp.AddTool(s, &mcp.Tool{
+		InputSchema: mapSiteSchema(),
+	}, dataHandler(retrieval.MapSitePage))
+	s.AddTool(&mcp.Tool{
 		Name:        "research",
 		Title:       "Find data sources",
 		Description: "Discover real-world information sources and their available operations. Search semantically, browse all sources, groups or operations, filter by websites/source IDs/categories, and paginate. Free; returns IDs and copy-ready inspect calls. Use read_link for regular documentation.",
 		Annotations: &mcp.ToolAnnotations{ReadOnlyHint: true},
-	}, func(_ context.Context, _ *mcp.CallToolRequest, input retrieval.ResearchInput) (*mcp.CallToolResult, any, error) {
-		result, err := retrieval.Research(input)
-		return dataMCPResult(result, err)
-	})
-	mcp.AddTool(s, &mcp.Tool{
+		InputSchema: researchDataSchema(),
+	}, dataHandler(retrieval.Research))
+	s.AddTool(&mcp.Tool{
 		Name:        "inspect",
 		Title:       "Inspect a data source or operation",
 		Description: "Explore operations in a source, or inspect one operation's EXACT input types, required fields, constraints, output contract, pricing, and examples. Returns the next execute call with the exact input keys to fill. Free.",
 		Annotations: &mcp.ToolAnnotations{ReadOnlyHint: true},
-	}, func(_ context.Context, _ *mcp.CallToolRequest, input retrieval.InspectInput) (*mcp.CallToolResult, any, error) {
-		result, err := retrieval.Inspect(input)
-		return dataMCPResult(result, err)
-	})
-	mcp.AddTool(s, &mcp.Tool{
+		InputSchema: inspectDataSchema(),
+	}, dataHandler(retrieval.Inspect))
+	s.AddTool(&mcp.Tool{
 		Name:        "execute",
 		Title:       "Query a data source (uses credits)",
-		Description: "Execute 1-10 inspected structured-data operations using their exact source IDs and inputs. Charges Firecrawl Alexandria credits after server-side schema and credit-budget checks. Supports pagination/continuations, stable request_id for safe retries, and original provider JSON. No third-party terms are accepted automatically.",
-		Annotations: &mcp.ToolAnnotations{ReadOnlyHint: false, DestructiveHint: func() *bool { v := false; return &v }()},
-	}, func(_ context.Context, _ *mcp.CallToolRequest, input retrieval.ExecuteInput) (*mcp.CallToolResult, any, error) {
-		result, err := retrieval.Execute(input)
-		return dataMCPResult(result, err)
-	})
+		Description: "Execute 1-10 inspected structured-data operations using exact operation IDs and inputs. Alexandria credits are charged automatically; the server enforces its configured 200-credit per-request ceiling. Actual credits are reported. Supports pagination, safe request_id retries and provider-native JSON. Does not accept third-party terms.",
+		Annotations: &mcp.ToolAnnotations{ReadOnlyHint: true},
+		InputSchema: executeDataSchema(),
+	}, dataHandler(retrieval.Execute))
 	return s
 }
 
+// Keep client-facing types narrow and self-describing. The SDK's default
+// reflection makes optional slices nullable and string enums unconstrained;
+// the catalogue operations support neither ambiguity.
+func researchDataSchema() *jsonschema.Schema {
+	schema, err := jsonschema.For[retrieval.ResearchInput](nil)
+	if err != nil {
+		panic(err)
+	}
+	schema.Properties["mode"].Enum = []any{"ranked", "catalogue"}
+	schema.Properties["view"].Enum = []any{"sources", "groups", "operations"}
+	for _, key := range []string{"mode", "view"} {
+		schema.Properties[key].Type = "string"
+		schema.Properties[key].Types = nil
+	}
+	for _, key := range []string{"urls", "sources", "categories", "groups", "operations", "include"} {
+		p := schema.Properties[key]
+		p.Type = "array"
+		p.Types = nil
+	}
+	schema.Properties["include"].Items.Enum = []any{"inputs", "output", "examples"}
+	return schema
+}
+
+func inspectDataSchema() *jsonschema.Schema {
+	schema, err := jsonschema.For[retrieval.InspectInput](nil)
+	if err != nil {
+		panic(err)
+	}
+	p := schema.Properties["include"]
+	p.Type = "array"
+	p.Types = nil
+	p.Items.Enum = []any{"inputs", "output", "examples"}
+	return schema
+}
+
+func executeDataSchema() *jsonschema.Schema {
+	schema, err := jsonschema.For[retrieval.ExecuteInput](nil)
+	if err != nil {
+		panic(err)
+	}
+	countMin, countMax := 1, 10
+	p := schema.Properties["calls"]
+	p.Type = "array"
+	p.Types = nil
+	p.MinItems = &countMin
+	p.MaxItems = &countMax
+	return schema
+}
+
+func mapSiteSchema() *jsonschema.Schema {
+	schema, err := jsonschema.For[retrieval.MapInput](nil)
+	if err != nil {
+		panic(err)
+	}
+	return schema
+}
+
+// Manual validation keeps data errors in successful MCP tool responses rather
+// than surfacing them as client-side INVALID_ARGUMENT tool exceptions.
+func dataHandler[In any](fn func(In) (map[string]any, error)) mcp.ToolHandler {
+	return func(_ context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+		var input In
+		args := req.Params.Arguments
+		if len(args) == 0 {
+			args = []byte("{}")
+		}
+		decoder := json.NewDecoder(bytes.NewReader(args))
+		decoder.DisallowUnknownFields()
+		if err := decoder.Decode(&input); err != nil {
+			response, _, e := dataMCPResult(nil, &retrieval.DataError{Code: "invalid_arguments", Message: err.Error()})
+			return response, e
+		}
+		result, err := fn(input)
+		response, _, e := dataMCPResult(result, err)
+		return response, e
+	}
+}
+
 func dataMCPResult(result map[string]any, err error) (*mcp.CallToolResult, any, error) {
 	failed := err != nil
 	if failed {
 		// Use the shared error serializer to preserve codes, corrective details
 		// and provider-term acceptance URLs as structured tool output.
 		result = retrieval.DataErrorResult(err)
+		result["ok"] = false
+	} else {
+		result["ok"] = true
 	}
 	bytes, marshalErr := json.MarshalIndent(result, "", "  ")
 	if marshalErr != nil {
@@ -94,7 +170,9 @@ func dataMCPResult(result map[string]any, err error) (*mcp.CallToolResult, any,
 	return &mcp.CallToolResult{
 		Content:           []mcp.Content{&mcp.TextContent{Text: string(bytes)}},
 		StructuredContent: result,
-		IsError:           failed,
+		// Keep validation/provider failures in the structured result. Clients
+		// commonly convert isError=true to opaque INVALID_ARGUMENT exceptions.
+		IsError: false,
 	}, nil, nil
 }
 

package/pkg/origo/server_test.go

@@ -1,6 +1,7 @@
 package origo
 
 import (
+	"encoding/json"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -22,6 +23,57 @@ func request(t *testing.T, key, body string) *httptest.ResponseRecorder {
 	return response
 }
 
+func TestDataSchemasExposeExactEnumsAndNonNullableCalls(t *testing.T) {
+	t.Setenv("ORIGO_API_KEY", "secret")
+	result := request(t, "secret", `{"jsonrpc":"2.0","id":12,"method":"tools/list","params":{}}`)
+	if result.Code != 200 {
+		t.Fatalf("tools/list failed: %s", result.Body.String())
+	}
+	var decoded struct {
+		Result struct {
+			Tools []struct {
+				Name        string         `json:"name"`
+				InputSchema map[string]any `json:"inputSchema"`
+				Annotations map[string]any `json:"annotations"`
+			} `json:"tools"`
+		} `json:"result"`
+	}
+	if err := json.Unmarshal(result.Body.Bytes(), &decoded); err != nil {
+		t.Fatal(err)
+	}
+	schemas := map[string]map[string]any{}
+	for _, tool := range decoded.Result.Tools {
+		if tool.Annotations["readOnlyHint"] != true {
+			t.Fatalf("%s was not marked read-only", tool.Name)
+		}
+		if _, exists := tool.Annotations["openWorldHint"]; exists {
+			t.Fatalf("%s should omit openWorldHint", tool.Name)
+		}
+		schemas[tool.Name] = tool.InputSchema
+	}
+	if len(schemas) != 5 {
+		t.Fatalf("expected five tools, got %d", len(schemas))
+	}
+	props := func(name string) map[string]any { return schemas[name]["properties"].(map[string]any) }
+	mode := props("research")["mode"].(map[string]any)
+	view := props("research")["view"].(map[string]any)
+	if mode["type"] != "string" || len(mode["enum"].([]any)) != 2 ||
+		view["type"] != "string" || len(view["enum"].([]any)) != 3 {
+		t.Fatalf("research discovery schemas are not typed: mode=%#v view=%#v", mode, view)
+	}
+	incl := props("research")["include"].(map[string]any)
+	if incl["type"] != "array" || len(incl["items"].(map[string]any)["enum"].([]any)) != 3 {
+		t.Fatalf("include does not constrain allowed options: %#v", incl)
+	}
+	calls := props("execute")["calls"].(map[string]any)
+	if _, present := props("execute")["max_credits"]; present {
+		t.Fatal("execute still exposes credit-budget control")
+	}
+	if calls["type"] != "array" || calls["minItems"] != float64(1) || calls["maxItems"] != float64(10) {
+		t.Fatalf("execute calls must be non-null and 1–10 items: %#v", calls)
+	}
+}
+
 func TestServerRequiresConfiguredKey(t *testing.T) {
 	t.Setenv("ORIGO_API_KEY", "")
 	response := request(t, "somekey", `{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}`)
@@ -62,11 +114,11 @@ func TestFiveToolsWithProgressiveDataInterface(t *testing.T) {
 	if count := strings.Count(text, `"name":`); count != 5 {
 		t.Fatalf("expected exactly 5 tools, got %d: %s", count, text)
 	}
-	if count := strings.Count(text, `"readOnlyHint":true`); count != 4 {
-		t.Fatalf("expected the four free retrieval tools to be read-only, got %d: %s", count, text)
+	if count := strings.Count(text, `"readOnlyHint":true`); count != 5 {
+		t.Fatalf("expected all five MCP tools to declare readOnlyHint=true, got %d: %s", count, text)
 	}
-	if count := strings.Count(text, `"readOnlyHint":false`); count != 1 {
-		t.Fatalf("expected only paid execute to indicate effects on billing, got %d: %s", count, text)
+	if strings.Contains(text, `"readOnlyHint":false`) || strings.Contains(text, `"openWorldHint"`) || strings.Contains(text, `"destructiveHint"`) {
+		t.Fatalf("unexpected non-read-only or open-world/destructive annotations: %s", text)
 	}
 }
 

package/pkg/retrieval/data.go

@@ -6,8 +6,11 @@ type ResearchInput = app.ResearchDataInput
 type InspectInput = app.InspectDataInput
 type ExecuteInput = app.ExecuteDataInput
 type DataCall = app.DataCall
+type DataError = app.DataError
+type MapInput = app.MapSiteInput
 
 func Research(input ResearchInput) (map[string]any, error) { return app.ResearchData(input) }
 func Inspect(input InspectInput) (map[string]any, error)   { return app.InspectData(input) }
 func Execute(input ExecuteInput) (map[string]any, error)   { return app.ExecuteData(input) }
 func DataErrorResult(err error) map[string]any             { return app.DataErrorResult(err) }
+func MapSitePage(input MapInput) (map[string]any, error)   { return app.MapSitePage(input) }