Use OCL Mapper workflows through the OCL API for CIEL Lab MCP for retrive_mapping_candidates tool

[filiperochalopes]

User story

As an MCP user, I want the retrieve_mapping_candidates tool to use OCL Mapper as a retrieval mode so conversational tools such as Claude can use OCL Mapper candidates directly in the chat.

Use case

During a conversational mapping workflow, the LLM calls retrieve_mapping_candidates with OCL Mapper mode enabled. The MCP Server uses the authenticated user’s OCL token to retrieve candidates through the OCL API and returns them to the conversation.

Requirements

• Add an OCL Mapper mode to the retrieve_mapping_candidates MCP tool.
• Use the authenticated user’s OCL API token.
• Call the existing OCL matching APIs without requiring the OCL Mapper interface.
• Support the required matching configuration, including:
  • target repository
  • algorithm
  • filters
  • candidate limit
• Use $match to retrieve mapping candidates.
• Use $rerank when configured.
• Return structured candidate data to the LLM conversation.
• Include relevant candidate information:
  • code
  • display name
  • source
  • mapping type or relationship, when available
  • score or ranking information, when available
• Preserve OCL permission and Mapper access rules.
• Return clear API, authentication, and configuration errors to the MCP client.
• Reuse existing OCL Mapper capabilities instead of recreating matching logic inside CIEL Lab.

Acceptance criteria

• Given OCL Mapper mode is selected, retrieve_mapping_candidates retrieves candidates through the OCL API.
• The tool works without opening or interacting with the OCL Mapper frontend.
• Claude or another MCP client can use the returned candidates directly in a conversational workflow.
• Candidate results are returned in a consistent structured format.
• $rerank is applied only when enabled in the tool configuration.
• OCL authentication and authorization failures are returned as clear tool errors.
• Existing retrieval modes continue to work unchanged.

Context

The OCL Mapper frontend already uses the OCL API for matching and reranking. For this use case, only those API capabilities need to be exposed through retrieve_mapping_candidates.

The objective is not to reproduce the complete Map Project interface or orchestration workflow. It is to make OCL Mapper candidate retrieval available to conversational MCP clients.

Related issue:

#2632

[ocl-automation]

Automated Triage — 2026-08-05

Dimension	Score
Complexity	3
Scope	3
Clarity	2
Dependency	3
Risk	3

Decision: decision/human-review
Type: type/feature
Signals: signal/needs-spec, signal/has-dependencies

Moderate complexity involving API integration and authentication flow across multiple components (MCP server, OCL API, authentication layer). Clarity is low - requirements are cut off and implementation details are missing. Moderate risk since incorrect API integration could break mapping functionality.

---

Generated by ticket-triage pipeline v3. Model: anthropic/claude-sonnet-4 (openrouter).