Skip to content

Add Directory Total Identities Tool #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
patrickcping wants to merge 19 commits into
base: main
Choose a base branch
from
Open

Add Directory Total Identities Tool #16

patrickcping wants to merge 19 commits into from

Conversation

@patrickcping
Copy link
Collaborator

@patrickcping patrickcping commented Dec 1, 2025 •
edited
Loading

Change Description

This PR adds a new MCP tool collection for directory operations, starting with the get_total_identities_by_environment tool that retrieves total identity counts from PingOne environments.

Type of Change

  • New feature (non-breaking change that adds functionality)
  • Test updates

Related Issues

Relates to internal feature request for directory total identities reporting.

Testing

This PR has been tested with:

  • Unit tests
  • Manual testing

Commands Run

make test

Test Results

Expand Test Results 
$ make test
go test -v -timeout 1m ./...
?       github.com/pingidentity/pingone-mcp-server      [no test files]
=== RUN   TestRootCommand
--- PASS: TestRootCommand (0.00s)
PASS
ok      github.com/pingidentity/pingone-mcp-server/cmd  0.295s
=== RUN   TestRunCmd_Execute
=== RUN   TestRunCmd_Execute/default_configuration
=== RUN   TestRunCmd_Execute/custom_log_level
=== RUN   TestRunCmd_Execute/invalid_log_level
--- PASS: TestRunCmd_Execute (0.00s)
    --- PASS: TestRunCmd_Execute/default_configuration (0.00s)
    --- PASS: TestRunCmd_Execute/custom_log_level (0.00s)
    --- PASS: TestRunCmd_Execute/invalid_log_level (0.00s)
=== RUN   TestRunCmd_PersistentPreRunE
=== RUN   TestRunCmd_PersistentPreRunE/success
=== RUN   TestRunCmd_PersistentPreRunE/error
--- PASS: TestRunCmd_PersistentPreRunE (0.00s)
    --- PASS: TestRunCmd_PersistentPreRunE/success (0.00s)
    --- PASS: TestRunCmd_PersistentPreRunE/error (0.00s)
PASS
ok      github.com/pingidentity/pingone-mcp-server/cmd/run     0.289s
=== RUN   TestSessionCmd_Execute
=== RUN   TestSessionCmd_Execute/success_-_token_found
=== RUN   TestSessionCmd_Execute/success_-_no_token_found
--- PASS: TestSessionCmd_Execute (0.00s)
    --- PASS: TestSessionCmd_Execute/success_-_token_found (0.00s)
    --- PASS: TestSessionCmd_Execute/success_-_no_token_found (0.00s)
PASS
ok      github.com/pingidentity/pingone-mcp-server/cmd/session 0.251s
=== RUN   TestLogoutCmd_Execute
=== RUN   TestLogoutCmd_Execute/success_-_token_deleted
=== RUN   TestLogoutCmd_Execute/success_-_no_token_found
--- PASS: TestLogoutCmd_Execute (0.00s)
    --- PASS: TestLogoutCmd_Execute/success_-_token_deleted (0.00s)
    --- PASS: TestLogoutCmd_Execute/success_-_no_token_found (0.00s)
PASS
ok      github.com/pingidentity/pingone-mcp-server/cmd/logout  0.257s
=== RUN   TestClientFactory_Default
--- PASS: TestClientFactory_Default (0.00s)
=== RUN   TestClientFactory_Empty
--- PASS: TestClientFactory_Empty (0.00s)
PASS
ok      github.com/pingidentity/pingone-mcp-server/internal/sdk        0.283s
=== RUN   TestCommandError
--- PASS: TestCommandError (0.00s)
PASS
ok      github.com/pingidentity/pingone-mcp-server/internal/errs       0.254s
=== RUN   TestAllToolsRegistered
--- PASS: TestAllToolsRegistered (0.00s)
=== RUN   TestAllToolsHaveSchemas
=== RUN   TestAllToolsHaveSchemas/create_environment
=== RUN   TestAllToolsHaveSchemas/delete_environment
=== RUN   TestAllToolsHaveSchemas/get_environment
=== RUN   TestAllToolsHaveSchemas/list_environments
=== RUN   TestAllToolsHaveSchemas/update_environment
=== RUN   TestAllToolsHaveSchemas/create_application
=== RUN   TestAllToolsHaveSchemas/delete_application
=== RUN   TestAllToolsHaveSchemas/get_application
=== RUN   TestAllToolsHaveSchemas/list_applications
=== RUN   TestAllToolsHaveSchemas/update_application
=== RUN   TestAllToolsHaveSchemas/create_population
=== RUN   TestAllToolsHaveSchemas/delete_population
=== RUN   TestAllToolsHaveSchemas/get_population
=== RUN   TestAllToolsHaveSchemas/list_populations
=== RUN   TestAllToolsHaveSchemas/update_population
=== RUN   TestAllToolsHaveSchemas/get_total_identities_by_environment
--- PASS: TestAllToolsHaveSchemas (0.00s)
    --- PASS: TestAllToolsHaveSchemas/create_environment (0.00s)
    --- PASS: TestAllToolsHaveSchemas/delete_environment (0.00s)
    --- PASS: TestAllToolsHaveSchemas/get_environment (0.00s)
    --- PASS: TestAllToolsHaveSchemas/list_environments (0.00s)
    --- PASS: TestAllToolsHaveSchemas/update_environment (0.00s)
    --- PASS: TestAllToolsHaveSchemas/create_application (0.00s)
    --- PASS: TestAllToolsHaveSchemas/delete_application (0.00s)
    --- PASS: TestAllToolsHaveSchemas/get_application (0.00s)
    --- PASS: TestAllToolsHaveSchemas/list_applications (0.00s)
    --- PASS: TestAllToolsHaveSchemas/update_application (0.00s)
    --- PASS: TestAllToolsHaveSchemas/create_population (0.00s)
    --- PASS: TestAllToolsHaveSchemas/delete_population (0.00s)
    --- PASS: TestAllToolsHaveSchemas/get_population (0.00s)
    --- PASS: TestAllToolsHaveSchemas/list_populations (0.00s)
    --- PASS: TestAllToolsHaveSchemas/update_population (0.00s)
    --- PASS: TestAllToolsHaveSchemas/get_total_identities_by_environment (0.00s)
PASS
ok      github.com/pingidentity/pingone-mcp-server/internal/tools       0.359s
=== RUN   TestDirectoryCollection_Name
--- PASS: TestDirectoryCollection_Name (0.00s)
=== RUN   TestDirectoryCollection_ListTools
--- PASS: TestDirectoryCollection_ListTools (0.00s)
=== RUN   TestGetTotalIdentitiesByEnvironmentHandler_MockClient
=== RUN   TestGetTotalIdentitiesByEnvironmentHandler_MockClient/success_without_date_filters
=== RUN   TestGetTotalIdentitiesByEnvironmentHandler_MockClient/success_with_date_filters
=== RUN   TestGetTotalIdentitiesByEnvironmentHandler_MockClient/success_with_partial_data
=== RUN   TestGetTotalIdentitiesByEnvironmentHandler_MockClient/error_getting_total_identities
=== RUN   TestGetTotalIdentitiesByEnvironmentHandler_MockClient/error_-_no_total_identities_returned
=== RUN   TestGetTotalIdentitiesByEnvironmentHandler_MockClient/unauthorized_error
--- PASS: TestGetTotalIdentitiesByEnvironmentHandler_MockClient (0.00s)
    --- PASS: TestGetTotalIdentitiesByEnvironmentHandler_MockClient/success_without_date_filters (0.00s)
    --- PASS: TestGetTotalIdentitiesByEnvironmentHandler_MockClient/success_with_date_filters (0.00s)
    --- PASS: TestGetTotalIdentitiesByEnvironmentHandler_MockClient/success_with_partial_data (0.00s)
    --- PASS: TestGetTotalIdentitiesByEnvironmentHandler_MockClient/error_getting_total_identities (0.00s)
    --- PASS: TestGetTotalIdentitiesByEnvironmentHandler_MockClient/error_-_no_total_identities_returned (0.00s)
    --- PASS: TestGetTotalIdentitiesByEnvironmentHandler_MockClient/unauthorized_error (0.00s)
PASS
ok      github.com/pingidentity/pingone-mcp-server/internal/tools/directory     0.277s
PASS
ok      github.com/pingidentity/pingone-mcp-server/internal/tools/applications  0.270s
PASS
ok      github.com/pingidentity/pingone-mcp-server/internal/tools/environments  0.267s
PASS
ok      github.com/pingidentity/pingone-mcp-server/internal/tools/populations   0.266s
PASS
ok      github.com/pingidentity/pingone-mcp-server/internal/tools/schema        0.266s

All tests passing: ✅

Implementation Details

New Directory Collection

Added a new directory tool collection under internal/tools/directory/ with the following components:

  1. Collection Registration (collection.go)

    • Registers the directory collection with the MCP server
    • Provides collection metadata and tool listings

  2. Get Total Identities Tool (get_total_identities_by_environment.go)

    • Retrieves total identity counts for a PingOne environment
    • Supports optional date range filtering (startDate, endDate)
    • Returns structured data including identity counts and metadata

  3. Client Abstractions (client_interface.go, client_wrapper.go)

    • Interface for directory API operations
    • Wrapper implementation for PingOne SDK client
    • Enables easy mocking for unit tests

  4. Comprehensive Test Coverage (*_test.go)

    • 347 lines of test code for the main tool
    • 123 lines of collection tests
    • Mock client implementations for isolated testing
    • Test helpers for common patterns
    • Coverage for success cases, error handling, authentication, and edge cases

Schema Utilities Enhancement

Added EncodeFilterParam function to internal/tools/schema/schema_helpers.go:

  • URL-encodes filter parameters for API requests
  • Ensures proper handling of special characters in filter expressions

Tool Registration

Updated internal/tools/register.go to include the new directory collection in the server's tool registry.

Checklist

  • Code follows project style guidelines
  • Self-review completed
  • Tests added/updated as needed
  • All tests pass locally
  • No breaking changes

Dependencies

Important: This PR depends on an upcoming update to the PingOne Go SDK (pingone-go-client) to correct the data type of the total identities response payload. The current SDK implementation may need adjustments to properly handle the API response structure.

pingidentity/pingone-go-client#52

Additional Context

This is the first tool in the new directory collection. Future enhancements may include additional directory-related operations such as:

  • Identity search and filtering
  • User lifecycle operations
  • Group management
  • Directory attribute queries

The implementation follows existing patterns from the environments, applications, and populations collections for consistency.

patrickcping and others added 16 commits November 28, 2025 18:04
@patrickcping
Add directory collection with get_total_identities_by_environment_id …
341e4e2 
…tool

- Add new directory collection with DirectoryClient interface
- Implement GetTotalIdentitiesByEnvironmentId tool for retrieving user identity counts
- Add comprehensive test coverage including mock client tests
- Tool supports custom date ranges with sensible defaults (32-day period)
- Register directory collection in tool registry
- All tests passing (13 tests, 100% pass rate)
@patrickcping
corrections to filter and response object
1157ceb
@patrickcping
add url encoding of the filter
70578e5
@patrickcping
minor fixes
f758766
@patrickcping
fixed register testing
a4e2e02
@patrickcping
Merge branch 'main' into feature/add-directory-total-identities-tool/…
a48f228 
…pc/20241128
@patrickcping
updates for changes to main
4e0e6f9
@patrickcping
feat: warn users when write tools are filtered due to read-only mode
bd13497 
Add warning message when users specify write tools with --include-tools
but forget to add --disable-read-only flag. This helps users understand
why their specified tools aren't available and provides clear guidance
on how to enable them.

The warning:
- Detects write tools in the --include-tools list
- Warns with specific tool names that will be filtered
- Suggests adding --disable-read-only flag to enable them
@patrickcping
docs: improve README and add comprehensive setup and troubleshooting …
cc9639d 
…guides

- Improve PingOne setup section readability with better structure and formatting
- Fix Linux installation instructions to match macOS style and correct URLs
- Add comprehensive worker application setup guide (docs/setup-pingone-worker-application.md)
  - Detailed instructions for both Authorization Code and Device Authorization grants
  - Manual (PingOne console) and automated (Ping CLI) setup options
  - Administrative user setup and role assignment guidance
  - Verification steps and security best practices
- Add comprehensive troubleshooting guide (docs/troubleshooting.md)
  - Debug mode configuration and usage
  - Authentication issues (8 common scenarios)
  - Configuration issues (5 common scenarios)
  - Runtime and tool execution issues
  - MCP client integration issues
  - Guidance on getting additional help
- Update README to reference new documentation
- Consolidate troubleshooting information from multiple locations
@henryrecker-pingidentity
Fix workflow links
5d92f82
@henryrecker-pingidentity
Fix issues link
c4a504c
@henryrecker-pingidentity
Remove inaccurate security descriptions
efc3616
@patrickcping
Merge branch 'main' into feature/add-directory-total-identities-tool/…
5ff29d5 
…pc/20241128
@patrickcping
tool updates
5e6984d
@patrickcping
Merge branch 'docs/improve-readme-and-setup-docs/pc/20251211' into fe…
47fcd56 
…ature/add-directory-total-identities-tool/pc/20241128
@patrickcping
add to readme
b23991c
@patrickcping patrickcping changed the base branch from main to docs/improve-readme-and-setup-docs/pc/20251211 December 11, 2025 16:34
Base automatically changed from docs/improve-readme-and-setup-docs/pc/20251211 to main December 11, 2025 19:53
@patrickcping patrickcping marked this pull request as ready for review December 12, 2025 11:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@henryrecker-pingidentity henryrecker-pingidentity Awaiting requested review from henryrecker-pingidentity henryrecker-pingidentity is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@patrickcping @henryrecker-pingidentity