feature-evaluator（特征评估器）

Feature Evaluator MCP

MCP integration for the Feature Evaluator — a feature flag system with rule-based evaluation, segment targeting, and pack-based feature bundling.

MCP Proxy

This project uses mcp-openapi-proxy to auto-generate MCP tools from the OpenAPI spec. Each API endpoint becomes a callable tool that executes real HTTP requests.

Repository: https://github.com/rendis/mcp-openapi-proxy Install: go install github.com/rendis/mcp-openapi-proxy/cmd/mcp-openapi-proxy@latest Docs: See mcp-openapi-proxy README for full configuration, authentication, and troubleshooting.

Setup

Claude Code

The project includes a .mcp.json — Claude Code auto-detects it. No manual setup needed.

make server       # Start API on port 8080
# MCP auto-configured via .mcp.json → mcp-openapi-proxy reads the Swagger spec

Verify: claude mcp list → should show feature-evaluator connected.

OpenAI Codex

Edit ~/.codex/config.toml:

[mcp_servers.feature-evaluator]
command = "mcp-openapi-proxy"
args = []

[mcp_servers.feature-evaluator.env]
MCP_SPEC = "https://raw.githubusercontent.com/rendis/feature-evaluator/main/server/docs/swagger.yaml"
MCP_BASE_URL = "<your-api-url>/features"
MCP_TOOL_PREFIX = "fe"

Gemini CLI

Edit ~/.gemini/settings.json (global) or .gemini/settings.json (project):

{
  "mcpServers": {
    "feature-evaluator": {
      "command": "mcp-openapi-proxy",
      "args": [],
      "env": {
        "MCP_SPEC": "https://raw.githubusercontent.com/rendis/feature-evaluator/main/server/docs/swagger.yaml",
        "MCP_BASE_URL": "<your-api-url>/features",
        "MCP_TOOL_PREFIX": "fe"
      }
    }
  }
}

Regenerate Swagger (after handler changes)

make swagger      # generates server/docs/swagger.yaml from handler annotations

OIDC Authentication (production)

mcp-openapi-proxy login     # browser-based OIDC PKCE login
mcp-openapi-proxy status    # check auth status
mcp-openapi-proxy logout    # clear stored tokens

Available MCP Tools

Each API endpoint becomes a callable MCP tool. Tool naming pattern: fe_{operation}.

Key Tools

All tools follow the fe_* prefix convention. Run any fe_list_* tool to discover available resources.

Quick Start Workflow

1. fe_list_features                → discover existing features
2. fe_get_feature { key: "..." }   → inspect a specific feature
3. fe_list_rules { key: "..." }    → see targeting rules
4. fe_evaluate { featureKey: "...", context: {...} }  → evaluate a feature
5. fe_expression_schema            → see available expression fields/functions
6. fe_validate_expression { expression: "..." }       → validate rule syntax

API Groups

All routes under base path /features.

Health (no auth)

• GET /healthz, GET /readyz

Evaluation (Bearer OR X-Api-Key + rate limited)

• POST /eval — evaluate single feature
• POST /eval/bulk — evaluate multiple features
• POST /eval/active — evaluate all active features
• POST /eval/conversions — record experiment conversion

OFREP (OpenFeature Remote Evaluation Protocol)

• POST /ofrep/v1/evaluate/flags/:key — single flag (separate base path)
• POST /ofrep/v1/evaluate/flags — bulk flags

Features (Bearer JWT)

• CRUD: GET/POST/PUT/DELETE /admin/features, /admin/features/:key
• PATCH /admin/features/:key/toggle — enable/disable
• GET /admin/environments — list environments

Rules (Bearer JWT)

• CRUD: GET/POST/PUT/DELETE /admin/features/:key/rules
• PUT /admin/features/:key/rules/reorder
• POST/GET /admin/features/:key/expression/test, /expression-schema

Expression Tools (Bearer JWT)

• POST /admin/expression/validate — validate syntax
• POST /admin/expression/test — test with context
• GET /admin/expression/schema — available fields/functions

Schedules (Bearer JWT)

• POST/GET /admin/features/:key/schedules
• DELETE /admin/schedules/:id

Packs (Bearer JWT)

• CRUD: GET/POST/PUT/DELETE /admin/packs, /admin/packs/:key
• PATCH /admin/packs/:key/toggle
• POST/DELETE /admin/packs/:key/activate — activate/deactivate on target
• GET /admin/packs/:key/activations, /admin/packs/by-target

Segments (Bearer JWT)

• CRUD: GET/POST/PUT/DELETE /admin/segments, /admin/segments/:key
• GET /admin/segments/:key/schema, /admin/segments/:key/records
• POST /admin/segments/:key/data/import

Experiments (Bearer JWT)

• CRUD: GET/POST/PUT /admin/experiments, /admin/experiments/:id
• Lifecycle: POST /admin/experiments/:id/{start,pause,complete,declare-winner}
• GET /admin/experiments/:id/results

Tags, Members, API Keys, Auth Profiles, External APIs

• CRUD at /admin/tags, /admin/members, /admin/api-keys, /admin/auth-profiles, /admin/external-apis

Dashboard & Metrics (Bearer JWT)

• GET /admin/dashboard/{stats,activity,error-summary,operations}
• GET /admin/dashboard/metrics/{overview,features,reasons,tenants,environments,cache,external}

Audit & Changelog (Bearer JWT)

• GET /admin/audit/errors
• GET /admin/changelog, /admin/changelog/:entityType/:entityKey

Workspaces (Bearer JWT)

• CRUD: GET/POST/PUT/DELETE /admin/workspaces, /admin/workspaces/:key
• POST /admin/workspaces/:key/{archive,restore}

Tiers (Bearer JWT, read-only)

• GET /admin/tiers

Expression Language (expr-lang)

Rules use expr-lang/expr. Full reference: references/expressions.md

Eval Request

{
  "featureKey": "my-feature",
  "context": {
    "user": { "id": "u-1", "email": "alice@empresa.com", "role": "admin" },
    "tenant": { "id": "t-1" },
    "campus": { "id": "c-1" },
    "program": { "id": "p-1" },
    "custom": { "country": "US" },
    "billing": { "plan": "pro" }
  },
  "environment": "production"
}

Evaluation Inputs

• environment can be sent in the eval request body.
• X-Environment overrides body environment on eval endpoints.
• environment is used as a feature-level eligibility gate before rule evaluation. It is not documented as an expression variable.
• Each context namespace becomes a top-level variable in expressions (user.*, tenant.*, custom.*, billing.*, etc.).
• custom is valid and already supported.
• Any additional namespace under context is also exposed as a top-level variable.

See references/expressions.md for the full precedence and evaluation behavior.

System Headers vs Expression Headers

System headers affect request handling, auth, workspace resolution, or context fallbacks. They are not exposed to headers.* automatically just because they were sent.

headers.* only contains headers explicitly declared in the feature InputContract. If a feature maps a header like X-Region to expression key region, the rule can read headers.region.

Expression Variables

JWT auto-extraction: Send Authorization: Bearer <jwt> → claims sub, email, name auto-populate derived.*. JWT claims take priority over context body.

Builtin Functions

Common Patterns

# Email targeting (from JWT)
derived.email == "admin@empresa.com"
endsWith(derived.email, "@empresa.com")

# Email targeting (from context body)
user.email == "admin@empresa.com"

# Custom namespaces from context
custom.country == "CL"
billing.plan == "pro"

# Header declared in feature InputContract
headers.region == "us-east-1"

# Auth + role
authenticated && user.role == "admin"
derived.apiKeyPresent

# Segments
inSegment("beta-users")

# Date range
dateAfter(now(), "2025-06-01") && dateBefore(now(), "2025-12-31")

# Combined
tenant.id == "acme" && inSegment("early-access") && authenticated

Security Limits

Max AST depth: 10, max nodes: 100, max inSegment() calls: 5, max string length: 1000. Denied: exec, system, import, require, proto, constructor, prototype, eval, Function, process.

Known API Behaviors

• List responses: {"data": [...], "pagination": {"page": 1, "pageSize": 20, "total": N, "totalPages": M}}
• Toggle/Delete: return 204 No Content
• Errors: {"error": {"code": "...", "message": "...", "messageKey": "..."}}
• Pack targets: tenant, campus, program
• Value types: boolean, string, number, json
• Access policies: public (default), optional, required