FCCS MCP Agentic Server

Instructions

Implementation Reference

• fccs_agent/tools/feedback.py:9-59 (handler)

  The main async handler function that implements the submit_feedback tool logic: validates rating, interacts with feedback_service to store user feedback, and returns success/error status.

  async def submit_feedback(
      execution_id: int,
      rating: int,
      feedback: Optional[str] = None
  ) -> dict[str, Any]:
      """Submit user feedback for a tool execution to improve RL learning.
      
      This tool allows you to rate a tool execution (1-5 stars) and provide
      optional feedback. This helps the RL system learn which tools work best
      for your use cases and improves future recommendations.
      
      Args:
          execution_id: The ID of the tool execution to rate (from tool result)
          rating: Rating from 1-5 stars (5 = excellent, 1 = poor)
          feedback: Optional text feedback about the execution
      
      Returns:
          dict: Status of feedback submission
      """
      if rating < 1 or rating > 5:
          return {
              "status": "error",
              "error": f"Rating must be between 1 and 5, got {rating}"
          }
      
      feedback_service = get_feedback_service()
      if not feedback_service:
          return {
              "status": "error",
              "error": "Feedback service not available"
          }
      
      try:
          feedback_service.add_user_feedback(
              execution_id=execution_id,
              rating=rating,
              feedback=feedback
          )
          
          return {
              "status": "success",
              "message": f"Feedback submitted: {rating} stars",
              "execution_id": execution_id,
              "rating": rating,
              "feedback": feedback
          }
      except Exception as e:
          return {
              "status": "error",
              "error": f"Failed to submit feedback: {str(e)}"
          }

• fccs_agent/tools/feedback.py:105-127 (schema)

  The input schema definition for the submit_feedback tool, including properties for execution_id, rating (1-5), optional feedback, and required fields.

      "name": "submit_feedback",
      "description": "Submit user feedback (rating 1-5 stars) for a tool execution to improve RL learning / Enviar feedback do usuario para melhorar aprendizado RL",
      "inputSchema": {
          "type": "object",
          "properties": {
              "execution_id": {
                  "type": "integer",
                  "description": "The ID of the tool execution to rate (found in tool result or from get_recent_executions)",
              },
              "rating": {
                  "type": "integer",
                  "description": "Rating from 1-5 stars (5 = excellent, 4 = good, 3 = average, 2 = poor, 1 = bad)",
                  "minimum": 1,
                  "maximum": 5,
              },
              "feedback": {
                  "type": "string",
                  "description": "Optional text feedback about the execution",
              },
          },
          "required": ["execution_id", "rating"],
      },
  },

• fccs_agent/agent.py:138-185 (registration)

  Central registration of the submit_feedback tool handler in the TOOL_HANDLERS dictionary used by the agent to dispatch tool calls.

  TOOL_HANDLERS = {
      # Application
      "get_application_info": application.get_application_info,
      "get_rest_api_version": application.get_rest_api_version,
      # Jobs
      "list_jobs": jobs.list_jobs,
      "get_job_status": jobs.get_job_status,
      "run_business_rule": jobs.run_business_rule,
      "run_data_rule": jobs.run_data_rule,
      # Dimensions
      "get_dimensions": dimensions.get_dimensions,
      "get_members": dimensions.get_members,
      "get_dimension_hierarchy": dimensions.get_dimension_hierarchy,
      # Journals
      "get_journals": journals.get_journals,
      "get_journal_details": journals.get_journal_details,
      "perform_journal_action": journals.perform_journal_action,
      "update_journal_period": journals.update_journal_period,
      "export_journals": journals.export_journals,
      "import_journals": journals.import_journals,
      # Data
      "export_data_slice": data.export_data_slice,
      "smart_retrieve": data.smart_retrieve,
      "smart_retrieve_consolidation_breakdown": data.smart_retrieve_consolidation_breakdown,
      "smart_retrieve_with_movement": data.smart_retrieve_with_movement,
      "copy_data": data.copy_data,
      "clear_data": data.clear_data,
      # Reports
      "generate_report": reports.generate_report,
      "get_report_job_status": reports.get_report_job_status,
      "generate_report_script": reports.generate_report_script,
      # Consolidation
      "export_consolidation_rulesets": consolidation.export_consolidation_rulesets,
      "import_consolidation_rulesets": consolidation.import_consolidation_rulesets,
      "validate_metadata": consolidation.validate_metadata,
      "generate_intercompany_matching_report": consolidation.generate_intercompany_matching_report,
      "import_supplementation_data": consolidation.import_supplementation_data,
      "deploy_form_template": consolidation.deploy_form_template,
      "generate_consolidation_process_report": consolidation.generate_consolidation_process_report,
      # Memo
      "generate_system_pitch": memo.generate_system_pitch,
      "generate_investment_memo": memo.generate_investment_memo,
      # Feedback
      "submit_feedback": feedback.submit_feedback,
      "get_recent_executions": feedback.get_recent_executions,
      # Local Data
      "query_local_metadata": local_data.query_local_metadata,
  }

• fccs_agent/agent.py:188-199 (registration)

  Aggregation of tool definitions including feedback.TOOL_DEFINITIONS (which contains submit_feedback schema) into ALL_TOOL_DEFINITIONS for the MCP server.

  ALL_TOOL_DEFINITIONS = (
      application.TOOL_DEFINITIONS +
      jobs.TOOL_DEFINITIONS +
      dimensions.TOOL_DEFINITIONS +
      journals.TOOL_DEFINITIONS +
      data.TOOL_DEFINITIONS +
      reports.TOOL_DEFINITIONS +
      consolidation.TOOL_DEFINITIONS +
      memo.TOOL_DEFINITIONS +
      feedback.TOOL_DEFINITIONS +
      local_data.TOOL_DEFINITIONS
  )