convez.ai
MCP ServerIntegração & APIsAvançado
yuwang-csdp

KaaS MCP Server

yuwang-csdp/kaas-mcp-server

Orquestrador de recuperação de conhecimento Salesforce para agentes

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que implementa um serviço de orquestração de recuperação de conhecimento (Knowledge as a Service) para agentes. Fornece acesso unificado a fontes de conhecimento Salesforce como C360 e Data Graph, com suporte a busca híbrida, fan-out paralelo e observabilidade integrada.

Instalação

$npx convez-ai yuwang-csdp/kaas-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar agentes Salesforce (Help Agent, Slack Agent) com fontes de conhecimento C360
  • Implementar busca híbrida e recuperação paralela de múltiplas bases de conhecimento
  • Centralizar lógica de query understanding e response packaging para agentes

Veredito

Solução robusta para orquestração de retrieval em ambientes Salesforce/Agentforce, com arquitetura stateless, observabilidade nativa e interface dupla (REST + MCP). Recomendado para times que precisam centralizar acesso a múltiplas fontes de conhecimento em agentes enterprise.

README

A tradução para o português deste README ainda está na fila.

KaaS — Knowledge as a Service

A stateless retrieval orchestration service that sits between any agent caller and Salesforce knowledge sources (C360 hybrid search, Data Graph). It owns query understanding, parallel fan-out retrieval, response packaging, and observability — so consuming agents (Help Agent, Slack Agent, Informatica Agent) don't have to.

Design doc: kaas_design_working_new.md (living doc, not final spec) Forge ML platform: https://launchpad.forge-prod.sfdcbt.net/projects/141


Architecture

  OrgCS (hosted)
  ┌──────────────────────┐
  │  Help Agent          │──────────────────────────────────────────┐
  │  Slack Agent         │  (same agent, different channel surface) │
  └──────────────────────┘                                          │
                                                                     │
  Informatica Agent ───────────────────────────────────────────────┤
  Future agents    ───────────────────────────────────────────────┤
                                                                     │ HTTPS (API key)
                                                                     ▼
                      ┌─────────────────────────────────────┐
                      │            KaaS Service              │
                      │      (Forge EKS, always-on)         │
                      │                                     │
                      │  ┌──────────────────────────────┐  │
                      │  │   Retrieval Orchestrator      │  │
                      │  │  (parallel fan-out + merge)   │  │
                      │  └──────┬────────────┬───────────┘  │
                      │         │            │              │
                      │  ┌──────▼──┐  ┌─────▼──────────┐  │
                      │  │  C360   │  │  Data Graph     │  │
                      │  │  Hybrid │  │  Adapter (v2)   │  │
                      │  │  Search │  │  (flagged off)  │  │
                      │  └─────────┘  └────────────────┘  │
                      │                                     │
                      │  ┌──────────────────────────────┐  │
                      │  │  Logging / Tracing / Exp Mgmt │  │
                      │  └──────────────────────────────┘  │
                      └─────────────────────────────────────┘

Interface layers:

  • Layer 1 — REST API (MVP, canonical): clean JSON contract, any HTTP client. Auth, versioning, and observability live here.
  • Layer 2 — MCP server (v1.1, additive): thin wrapper exposing the same capabilities as named MCP tools for Agentforce/OrgCS native integration. REST callers are unaffected.

Project Structure

kaas-mcp-server/
├── main.py                    # uvicorn entry point
├── pyproject.toml
├── .env.example
└── kaas/
    ├── core/
    │   ├── config.py          # settings loaded from env vars
    │   └── models.py          # Pydantic request/response models
    ├── adapters/
    │   └── c360.py            # C360 retriever adapter (dummy placeholder)
    ├── api/
    │   ├── auth.py            # X-API-Key header validation
    │   ├── routes.py          # POST /v1/retrieve  POST /v1/feedback  GET /v1/health
    │   └── app.py             # FastAPI app
    └── mcp/
        └── server.py          # MCP server — search_knowledge, submit_feedback, get_health

Quickstart

pip install -e ".[dev]"

cp .env.example .env
# edit .env — set KAAS_API_KEYS to your own keys

# Start REST API
python main.py
# or: uvicorn kaas.api.app:app --reload

# Interactive API docs
open http://localhost:8000/docs

Running the MCP server

The MCP server proxies all calls to the running REST API over stdio (for Claude Desktop / Agentforce MCP client):

KAAS_BASE_URL=http://localhost:8000 \
KAAS_MCP_API_KEY=dev-key-1 \
python -m kaas.mcp.server

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "kaas": {
      "command": "python",
      "args": ["-m", "kaas.mcp.server"],
      "env": {
        "KAAS_BASE_URL": "http://localhost:8000",
        "KAAS_MCP_API_KEY": "your-key"
      }
    }
  }
}

Using MCP tools from AI coding clients

Any MCP-compatible AI client can call search_knowledge, submit_feedback, and get_health directly. The MCP server must be running (or launched on-demand by the client) with the REST API already up.

The config block is the same across clients — only the config file location differs:

ClientConfig file
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Claude Code (CLI)~/.claude/claude_desktop_config.json, or run: claude mcp add kaas -- python -m kaas.mcp.server
Cursor.cursor/mcp.json in the project root, or ~/.cursor/mcp.json globally
GitHub Copilot (VS Code).vscode/mcp.json in the project root
Windsurf~/.codeium/windsurf/mcp_config.json

All clients use the same JSON shape:

{
  "mcpServers": {
    "kaas": {
      "command": "python",
      "args": ["-m", "kaas.mcp.server"],
      "env": {
        "KAAS_BASE_URL": "http://localhost:8000",
        "KAAS_MCP_API_KEY": "your-key"
      }
    }
  }
}

Once configured, you can invoke the tools conversationally — for example, ask your AI assistant:

"Call search_knowledge with query 'how do I set up email settings' and agent_id 'test-agent'"

The client will call the MCP tool and return the response inline.


API Reference

POST /v1/retrieve

Main retrieval endpoint. Accepts a query + caller context, runs query intelligence, fans out to C360 hybrid search per detected product, and returns chunks grouped by product with an ambiguity signal block.

Request

{
  "query": "how do I set up email settings",
  "agent_id": "help-agent-orgcs",
  "filters": {
    "locale": "en-US",
    "product": "agentforce",
    "version": "spring-25"
  },
  "options": {
    "ambiguity_behavior": "fan_out",
    "top_k": 5,
    "max_products": 3
  },
  "caller_context": {
    "tenant_id": "...",
    "user_id": "..."
  },
  "correlation_id": "abc-123"
}

product and version in filters are optional. If product is omitted, KaaS runs the product classifier and fans out. caller_context is optional; when absent, graph lookup is skipped.

ambiguity_behavior:

  • fan_out (default) — retrieve across all candidate products, return chunks labeled by product
  • top_only — retrieve from highest-confidence product only, still signal ambiguity
  • signal_only — return only the ambiguity signal, no chunks

Response

{
  "request_id": "kaas-uuid-...",
  "correlation_id": "abc-123",
  "trace_id": "trace-...",
  "experiment_variant": "classifier_v1_rules_only",
  "latency_ms": {
    "query_intelligence": 42,
    "retrieval_total": 310,
    "retrieval_per_product": { "agentforce": 295, "sales_cloud": 310 },
    "total": 368
  },
  "query_intelligence": {
    "normalized_query": "how do I configure email settings",
    "intent": "how_to",
    "ambiguous": true,
    "ambiguity_type": "multi_product",
    "candidate_products": [
      { "product": "agentforce",  "confidence": 0.71, "detection_method": "rule" },
      { "product": "sales_cloud", "confidence": 0.58, "detection_method": "rule" }
    ],
    "suggested_clarification": "Are you asking about email settings in Agentforce or Sales Cloud?",
    "retrieval_scope_used": "fan_out",
    "feedback_token": "fb-opaque-token-..."
  },
  "results": [
    {
      "product": "agentforce",
      "chunks": [
        {
          "chunk_id": "c-001",
          "score": 0.91,
          "text": "...",
          "source_url": "https://help.salesforce.com/...",
          "doc_version": "spring-25",
          "metadata": { "section": "Email Channel Setup", "locale": "en-US" }
        }
      ]
    }
  ]
}

POST /v1/feedback

Submit a product correction or quality signal after a retrieval response. The feedback_token from /v1/retrieve links the correction back to the original request for classifier training (Phase 2).

{
  "feedback_token": "fb-opaque-token-...",
  "correct_product": "sales_cloud",
  "feedback_type": "product_correction",
  "agent_id": "help-agent-orgcs",
  "session_id": "optional"
}

feedback_type: product_correction | irrelevant_chunks | missing_content


GET /v1/health

Returns service liveness + dependency status.

{
  "status": "ok",
  "classifier_version": "rules-v0",
  "taxonomy_version": "0.1.0",
  "c360_connectivity": "dummy"
}

MCP Tools

ToolMaps toDescription
search_knowledgePOST /v1/retrieveRetrieve product-scoped knowledge chunks
submit_feedbackPOST /v1/feedbackSubmit a correction signal for classifier training
get_healthGET /v1/healthCheck service health and connectivity

Configuration

All settings are loaded from environment variables (or .env):

VariableDefaultDescription
KAAS_API_KEYSdev-key-1,dev-key-2Comma-separated inbound API keys
KAAS_GRAPH_ENABLEDfalseEnable Data Graph parallel leg (v2)
KAAS_DEFAULT_TOP_K5Default chunks per product
KAAS_DEFAULT_MAX_PRODUCTS3Default fan-out width cap
KAAS_BASE_URLhttp://localhost:8000MCP server → REST API base URL
KAAS_MCP_API_KEYdev-key-1API key used by the MCP server

Authentication

All REST endpoints (except /v1/health) require an X-API-Key header. One key per agent in production, managed in secrets manager.

curl -H "X-API-Key: dev-key-1" http://localhost:8000/v1/health

Deployment

Target: EKS app on Forge ML platform — Project 141. Forge EKS is the correct target (always-on custom API service, not SageMaker which is for ML inference endpoints).

CI/CD via ArgoCD + forge-config.yml. Custom ML models (future classifier, future reranker) deploy as SageMaker endpoints on the same Forge project.

Auth in production: service-to-service API keys stored in secrets manager. MuleSoft gateway is a thin passthrough (or retired) — new callers call KaaS directly.


Consuming Agents

AgentSurfaceNotes
Help AgentHelp portal (customer-facing)Hosted in OrgCS; same deployment as Slack Agent
Slack AgentSlack (internal/external async)Same codebase as Help Agent, different channel surface
Informatica AgentTBDThird-party corpus consumer; onboarding in parallel
Future agents—Internal teams onboard via API key request

Help Agent and Slack Agent share the same agent_id namespace in OrgCS. Default to a single OrgCS API key unless per-surface SLA tracking is needed.


Observability

SignalFormatSinkPurpose
Distributed tracesOTel spans (OTLP)New Relic / SplunkEnd-to-end request debugging
MetricsOTel metrics (OTLP)New RelicDashboards + alerting
Operational logsStructured JSONSplunkSearch by request_id / agent_id
Analytics eventsStructured JSONSnowflakeClassifier quality, experiment analysis
Experiment exposuresStructured JSONSnowflake (v2)GrowthBook join
On-callvia New Relic alertsPagerDutyLatency p95, error rate, ambiguous rate

correlation_id in the API maps to a W3C traceparent header, enabling end-to-end traces across OrgCS → KaaS → C360.


Classifier Evolution

PhaseMethodLatencyStatus
1 — MVPRule-based (YAML taxonomy) + zero-shot LLM fallback via Einstein LLM Gatewayrules ~1ms, LLM ~400–500msCurrent
2Feedback collection → labeled dataset (human review queue)—Planned
3Fine-tuned lightweight classifier (SageMaker endpoint on Forge)~20–50msPlanned

Phased Roadmap

MVP — current

REST API on Forge EKS, dummy C360 adapter, rule-based classifier stub, auth, health endpoint, MCP server layer.

V1.1

MCP server wired to Agentforce/OrgCS native MCP client; LLM fallback classifier via Einstein LLM Gateway; Neo4j/Data Graph parallel leg enabled via feature flag for internal pilot; Informatica Agent onboarded.

V1.2

GrowthBook experiment assignment; experiment exposure events → Snowflake; graph entitlement pre-scoping live; ambiguity threshold A/B experiment.

V2

Fine-tuned classifier on SageMaker; optional second-stage reranker; generation mode (opt-in); conversation state management.


TODO

Retrieval

  • Replace dummy C360 adapter with real POST /v1/retrievers/{retrieverApiName}/text-retrieval calls — confirm credential type and access path with Data Cloud team (Risk #1 in design doc)
  • Implement rule-based product classifier from YAML taxonomy (products.yaml) — coordinate c360_filter_value with ATS tagging team to ensure filter alignment
  • Add zero-shot LLM fallback classifier via Einstein LLM Gateway (Phase 1b); batch intent detection in the same call
  • Add per-product retriever routing via YAML c360_retriever_name field (for Informatica corpus)
  • Implement version extraction from query ("Spring '25", "25.1", version slugs) and pass as C360 filter

Graph (v2)

  • Implement C360 Data Graph adapter — DG_Tenants_Metrics (tenant/contract/SKU); validate endpoint, auth schema, and response envelope
  • Wire graph parallel leg in orchestrator (alongside C360 retrieval, budget 500ms, non-blocking)
  • Implement merge logic: graph entitlement conflict → downrank chunks, log graph_entitlement_conflict: true
  • Meet graph readiness gate before enabling in production (p95 < 500ms, schema validated, no PII in graph paths)

Observability

  • Wire OTel instrumentation — spans for auth, query_intelligence, parallel_fan_out, c360.retrieve[product], packaging
  • Structured request log → Splunk (ops); analytics events + raw query (PII-scrubbed) → Snowflake
  • New Relic metrics: kaas.latency_ms, kaas.error_rate, kaas.c360.error_rate, kaas.classifier.ambiguous_rate, kaas.classifier.llm_fallback_rate
  • PagerDuty alert thresholds: p95 > 4s for 5min, error rate > 5% for 2min
  • Feedback event pipeline: write feedback_submitted events to label store (Snowflake) with feedback_token → request_id linkage

Deployment

  • Write forge-config.yml for EKS app deployment on Forge Project 141
  • Set up ArgoCD pipeline
  • Move API keys to secrets manager; provision one key per agent (OrgCS, Informatica)
  • Add forge-config.yml SageMaker endpoint config for future classifier model

Product taxonomy

  • Create products.yaml with exact_keywords, fuzzy_patterns, negative_keywords, c360_filter_value, description per product
  • Validate each c360_filter_value end-to-end: known article → C360 retrieval → non-empty results (add to CI smoke tests)
  • Sync with ATS tagging team on product identifier alignment (R16)

Auth & multi-tenancy

  • Enforce per-agent isolation in retrieval: OrgCS agent must not see Informatica Agent's retrieval context
  • Propagate correlation_id as W3C traceparent header to C360 and graph downstream calls

Experiments

  • Implement pluggable experiment flag abstraction (config/env in MVP; GrowthBook interface slot for v2)
  • Tag experiment_variant on every request log event from day one
  • Wire GrowthBook SDK on Forge when available (R4)

Privacy & compliance

  • Confirm PIA process with Legal/Privacy team before MVP launch (A7 in design doc)
  • Implement regex PII scrub (email, phone, SSN) before writing raw query to Snowflake
  • Document Snowflake retention policy and access controls

Testing

  • Integration smoke test: for each product in taxonomy, assert non-empty chunks returned
  • Contract test: verify C360 adapter request schema matches Data Cloud API spec
  • Load test: p95 < 3–4s at expected OrgCS help portal traffic volume
Ver o original no GitHub

Bom para

Relacionados