Preface

When developing agents in the DeepSeek Harness (DSH) ecosystem, handling geographic data usually requires manual parsing or integration with multiple external interfaces. The xby-philippine-geocoding plugin provides a standardized way to access the Philippine Standard Geocoding (PSGC) API directly through the Model Context Protocol (MCP). Maintained by xby-skill, the plugin includes complete Philippine geographic hierarchy data and can meet agents’ query needs when processing Philippine geographic information.

Core Features

The plugin provides full access to Philippine geographic hierarchy data. Its main features include:

  1. Basic Hierarchy Queries
    - Retrieve lists of island groups, regions, provinces, cities, municipalities, barangays, and administrative districts.
    - Retrieve detailed information for a specific geographic entity based on its code.

  2. Hierarchical Filtered Queries
    - Retrieve provinces, cities, municipalities, and barangays by region.
    - Retrieve cities, municipalities, and barangays by province.
    - Retrieve barangays by city.
    - Retrieve dependent cities, municipalities, and barangays by administrative district.

  3. Auxiliary Features
    - Search: Search geographic entities across all hierarchy levels by name.
    - Hierarchy Structure: Retrieve the complete parent hierarchy for a specific code.
    - Code Validation: Verify whether a geographic code exists and identify its type.
    - API Configuration: Set an API key in chat, with automatic persistence supported.

Installation and Enablement

Installing this plugin requires the dsh command-line tool and specifying a configuration file (the web profile is used in the examples).

dsh plugin --profile web add github:xby_skill/xby-philippine-geocoding

Method 2: Install from a Local Directory

dsh plugin --profile web add /absolute/path/to/xby-philippine-geocoding

Obtain the API Key

Before using the plugin, you need to configure the API key in chat. Register on the XBY official website and obtain the key, then execute the set_xby_apikey command in the DSH session.

Typical Usage

  1. Configure the Key
    Set the API key in the DSH chat window:
   set_xby_apikey <your_api_key>
  1. Search Geographic Entities
    Search for a specific location by name, for example “Metro Manila”:
   search_by_name Metro Manila
  1. Retrieve Hierarchy Information
    Query the complete geographic hierarchy for a specific code:
   get_hierarchy <psgc_code>
  1. Validate a Code
    Verify whether a PSGC code is valid:
   validate_code <code>

Applicable Scenarios and Notes

This plugin is suitable for DSH agent developers who need to accurately retrieve Philippine geographic hierarchy data (PSGC). Keep the following in mind when using it:

  • The plugin runs with the permissions of the current DSH process, so ensure that the API key is correctly set in the configuration file.
  • It is recommended to review the source code before installation to confirm that it meets your project requirements.
  • The plugin is licensed under the MIT License.

Conclusion

The xby-philippine-geocoding plugin provides a standardized solution for Philippine geographic data processing in the DeepSeek Harness ecosystem. Developers can perform precise geocoding queries through the MCP interface without maintaining complex geographic data structures themselves.