FCCS MCP Agentic Server

Instructions

Implementation Reference

• fccs_agent/tools/application.py:27-34 (handler)

  The main MCP tool handler function that fetches the REST API version using the global FCCS client and returns it wrapped in a standardized success response.

  async def get_rest_api_version() -> dict[str, Any]:
      """Get the REST API version / Obter a versao da API REST.
  
      Returns:
          dict: API version information.
      """
      version = await _client.get_rest_api_version()
      return {"status": "success", "data": version}

• fccs_agent/tools/application.py:48-54 (schema)

  The tool schema definition specifying the name, description, and empty input schema (no parameters required). Part of TOOL_DEFINITIONS list.

      "name": "get_rest_api_version",
      "description": "Get the REST API version / Obter a versao da API REST",
      "inputSchema": {
          "type": "object",
          "properties": {},
      },
  },

• fccs_agent/agent.py:141-141 (registration)

  Registration of the tool handler in the central TOOL_HANDLERS dictionary used by the agent to dispatch tool calls.

  "get_rest_api_version": application.get_rest_api_version,

• fccs_agent/client/fccs_client.py:96-113 (helper)

  The underlying FCCSClient method that actually queries the REST API (or mock) for the version information, called by the tool handler.

  async def get_rest_api_version(self) -> dict[str, Any]:
      """Get REST API version / Obter versao da API REST."""
      if self.config.fccs_mock_mode:
          return {"version": self.config.fccs_api_version, "apiVersion": "3.0"}
  
      # Try version endpoints
      for endpoint in ["/rest/version", "/version", "/api/version"]:
          try:
              response = await self._client.get(endpoint)
              if response.status_code == 200:
                  return response.json()
          except Exception:
              continue
  
      return {
          "version": self.config.fccs_api_version,
          "note": "Version endpoint not available, using configured version"
      }

• fccs_agent/agent.py:35-138 (helper)

  The full TOOL_HANDLERS dictionary where all tools are registered, including get_rest_api_version.

      if _fccs_client is None:
          _fccs_client = FccsClient(config)
      return _fccs_client
  
  
  def get_app_name() -> Optional[str]:
      """Get the current application name."""
      return _app_name
  
  
  async def initialize_agent(cfg: Optional[FCCSConfig] = None) -> str:
      """Initialize the agent and connect to FCCS.
  
      Returns:
          str: The application name or error message.
      """
      global _fccs_client, _app_name
  
      use_config = cfg or config
  
      # Initialize FCCS client
      _fccs_client = FccsClient(use_config)
  
      # Set client reference in all tool modules
      application.set_client(_fccs_client)
      jobs.set_client(_fccs_client)
      dimensions.set_client(_fccs_client)
      journals.set_client(_fccs_client)
      data.set_client(_fccs_client)
      reports.set_client(_fccs_client)
      consolidation.set_client(_fccs_client)
      memo.set_client(_fccs_client)
  
      # Initialize feedback service (optional - don't break if it fails)
      feedback_service = None
      try:
          feedback_service = init_feedback_service(use_config.database_url)
          print("Feedback service initialized", file=sys.stderr)
      except Exception as e:
          print(f"Warning: Could not initialize feedback service: {e}", file=sys.stderr)
          print("Tool execution will continue without feedback tracking", file=sys.stderr)
          # Set feedback service to None so callbacks know it's not available
          from fccs_agent.services.feedback_service import _feedback_service
          import fccs_agent.services.feedback_service as feedback_module
          feedback_module._feedback_service = None
  
      # Initialize cache service
      try:
          init_cache_service(use_config.database_url)
          print("Cache service initialized", file=sys.stderr)
      except Exception as e:
          print(f"Warning: Could not initialize cache service: {e}", file=sys.stderr)
  
      # Initialize RL service (optional - only if feedback service is available and RL enabled)
      if use_config.rl_enabled and feedback_service:
          try:
              init_rl_service(
                  feedback_service,
                  use_config.database_url,
                  exploration_rate=use_config.rl_exploration_rate,
                  learning_rate=use_config.rl_learning_rate,
                  discount_factor=use_config.rl_discount_factor,
                  min_samples=use_config.rl_min_samples
              )
              print("RL service initialized", file=sys.stderr)
          except Exception as e:
              print(f"Warning: Could not initialize RL service: {e}", file=sys.stderr)
              print("RL features will be disabled", file=sys.stderr)
  
      # Try to connect to FCCS and get application name
      try:
          print("Connecting to FCCS to retrieve application info...", file=sys.stderr)
          apps = await _fccs_client.get_applications()
          if apps and apps.get("items") and len(apps["items"]) > 0:
              _app_name = apps["items"][0]["name"]
              print(f"Connected to FCCS Application: {_app_name}", file=sys.stderr)
  
              # Set app name in tool modules that need it
              jobs.set_app_name(_app_name)
              dimensions.set_app_name(_app_name)
              journals.set_app_name(_app_name)
              data.set_app_name(_app_name)
              consolidation.set_app_name(_app_name)
              memo.set_app_name(_app_name)
  
              return _app_name
          else:
              print("No applications found", file=sys.stderr)
              return "No applications found"
      except Exception as e:
          print(f"Initialization warning: Could not connect to FCCS: {e}", file=sys.stderr)
          return f"Connection failed: {e}"
  
  
  async def close_agent():
      """Clean up agent resources."""
      global _fccs_client
      if _fccs_client:
          await _fccs_client.close()
          _fccs_client = None
  
  
  # Tool registry - maps tool names to handler functions
  TOOL_HANDLERS = {