mcp-vcd

Instructions

Implementation Reference

• src/mcp_vcd/server.py:108-142 (handler)

  Executes the get-signal tool: extracts arguments, parses signal mappings if needed, looks up the signal character, retrieves matching lines using get_signal_lines, and returns the output or error.

  if name == "get-signal":
      file_name = arguments.get("file_name")
      signal_name = arguments.get("signal_name")
      start_time = arguments.get("start_time")
      end_time = arguments.get("end_time")
  
      if not file_name or not signal_name:
          raise ValueError("Missing required parameters")
  
      try:
          # Get or update signal mappings for this file
          if file_name not in signal_mappings:
              signal_mappings[file_name] = await parse_signal_mappings(file_name)
  
          # Look up the character for this signal
          signal_char = signal_mappings[file_name].get(signal_name)
          if not signal_char:
              return [types.TextContent(
                  type="text",
                  text=f"Signal '{signal_name}' not found in VCD file"
              )]
  
          # Get all lines containing this character within time range
          output = await get_signal_lines(file_name, signal_char, start_time, end_time)
  
          return [types.TextContent(
              type="text",
              text=output if output else "No match"
          )]
  
      except Exception as e:
          return [types.TextContent(
              type="text",
              text=str(e)
          )]

• src/mcp_vcd/server.py:72-93 (schema)

  JSON schema defining the input parameters for the get-signal tool.

  inputSchema={
      "type": "object",
      "properties": {
          "file_name": {
              "type": "string",
              "description": "Name of the VCD file to analyze",
          },
          "signal_name": {
              "type": "string",
              "description": "Name of the signal to search for",
          },
          "start_time": {
              "type": "integer",
              "description": "Start timestamp (optional)",
          },
          "end_time": {
              "type": "integer",
              "description": "End timestamp (optional)",
          },
      },
      "required": ["file_name", "signal_name"],
  },

• src/mcp_vcd/server.py:62-96 (registration)

  Registers the get-signal tool via the list_tools handler, including name, description, and schema.

  @server.list_tools()
  async def handle_list_tools() -> list[types.Tool]:
      """
      List available tools.
      Each tool specifies its arguments using JSON Schema validation.
      """
      return [
          types.Tool(
              name="get-signal",
              description="Get all instances of a specified signal in a VCD file",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "file_name": {
                          "type": "string",
                          "description": "Name of the VCD file to analyze",
                      },
                      "signal_name": {
                          "type": "string",
                          "description": "Name of the signal to search for",
                      },
                      "start_time": {
                          "type": "integer",
                          "description": "Start timestamp (optional)",
                      },
                      "end_time": {
                          "type": "integer",
                          "description": "End timestamp (optional)",
                      },
                  },
                  "required": ["file_name", "signal_name"],
              },
          ),
      ]

• src/mcp_vcd/server.py:30-60 (helper)

  Helper function to extract lines from VCD file containing the specific signal character within a time range.

  async def get_signal_lines(file_name: str, char: str, start_time: Optional[int] = None, end_time: Optional[int] = None) -> str:
      """Get all lines containing the specified character within the timestamp range."""
      try:
          matches = []
          current_time = 0
          with open(file_name, 'r') as f:
              for line_num, line in enumerate(f, 1):
                  line = line.rstrip()
  
                  # Update current timestamp if we see a timestamp marker
                  if line.startswith('#'):
                      try:
                          current_time = int(line[1:])
                      except ValueError:
                          continue
  
                  # Skip if we're before start_time
                  if start_time is not None and current_time < start_time:
                      continue
  
                  # Break if we're past end_time
                  if end_time is not None and current_time > end_time:
                      break
  
                  # If we're in the desired time range and line contains our character
                  if char in line:
                      matches.append(f"{line_num}:{line}")
  
          return '\n'.join(matches)
      except Exception as e:
          raise RuntimeError(f"Failed to read file: {str(e)}")

• src/mcp_vcd/server.py:13-29 (helper)

  Helper function to parse the VCD file definitions section and map signal names to their single-character codes.

  async def parse_signal_mappings(file_name: str) -> Dict[str, str]:
      """Parse VCD file to extract signal name to character mappings."""
      mappings = {}
      try:
          with open(file_name, 'r') as f:
              for line in f:
                  if line.startswith('$enddefinitions'):
                      break
                  if line.startswith('$var'):
                      parts = line.split()
                      if len(parts) >= 5:
                          char, signal = parts[3], parts[4]
                          mappings[signal] = char
          return mappings
      except Exception as e:
          raise RuntimeError(f"Failed to parse signal mappings: {str(e)}")