senzing-entity-resolution
Guides AI agents through Senzing entity resolution workflows using the Senzing MCP server. Covers data mapping to Senzing format, SDK code generation (Python, Java, C#, Rust, TypeScript/Node.js), documentation search, error troubleshooting, sample data access, reporting and visua
Install
npx skills add https://github.com/Senzing/senzing-mcp-skill/tree/main/senzing-entity-resolution
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install senzing-senzing-mcp-skill@llmmart
git clone https://github.com/Senzing/senzing-mcp-skill.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole senzing/senzing-mcp-skill collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Senzing entity resolution — MCP skill
Use this skill whenever a task involves entity resolution, record linkage, deduplication or any interaction with the SENZING® SDK.
What the Senzing SDK is
Senzing software provides real time AI powered entity resolution as an embeddable SDK. It determines when two records refer to the same real-world entity (person, organization, etc.) by analyzing names, addresses, identifiers and other attributes across data sources — without training data or manual rules.
MCP Server Setup
The Senzing MCP server is a remote server. Connect it to your client:
Claude Code:
claude mcp add --transport http senzing https://mcp.senzing.com/mcp
Claude Desktop / Other MCP Clients — add to your MCP config:
{
"mcpServers": {
"senzing": {
"type": "url",
"url": "https://mcp.senzing.com/mcp"
}
}
}
The server works from pre-fetched documentation — it never connects to live
Senzing instances and never handles PII. It also hosts official Senzing SDK
.deb packages at /downloads/ for direct download in firewalled environments
— sdk_guide returns download URLs and install commands automatically.
Tool reference
Start any Senzing session by calling get_capabilities for an up-to-date
tool listing and suggested workflows.
Data mapping (3 tools)
| Tool | Purpose |
|---|---|
mapping_workflow |
Interactive 8-step workflow. Works with no readable source file: file_paths is a label, never opened by the server. Steps 1–4 (core): profile source data → plan entities → map fields → generate & validate. Steps 5–8 (optional): sandbox load into a fresh SQLite DB to catch mapping issues. State is client-side — always pass state back. Requires workspace_dir (a writable directory) on action='start' — pass it at the top level, or inside data; both are accepted. Optional environment (snowflake, aws_lambda, azure_functions, kafka, spark, or an alias such as lambda/spcs/databricks): pass it when the user says they run on one of these; on start the response's FIRST field is then environment_note — relay its rules to the user and run its search_docs query before writing code or SQL. Unknown value → is_error listing the valid ones. Dotted DB.SCHEMA.TABLE file labels infer snowflake. |
analyze_record |
Returns a Python analyzer script that examines feature distribution, attribute coverage, and data quality, and validates records against the Entity Specification — all locally. No source data is sent. Requires workspace_dir. |
download_resource |
Fallback for fetching workflow resources (analyzer, entity spec, mapping examples) when network restrictions block direct download. Batch-capable: pass filenames (array) for multiple resources or filename (string) for one. A large file comes back in chunks of at most 36,000 characters carrying truncated, next_offset and total_chars — pass offset=<next_offset> to continue; for .md reference documents search_docs is the cheaper route, and a batch member too large for one chunk is listed under oversize (request it alone). |
Documentation & reference (3 tools)
| Tool | Purpose |
|---|---|
search_docs |
Full-text search across entity specification, SDK guides, quickstarts, database tuning, pricing, architecture, globalization, EDA/data analysis, engine configuration, error codes, release notes, and PoC methodology. Prefer this over web search for any Senzing question. Use category='anti_patterns' to check for known pitfalls before recommending installation, architecture, or deployment approaches. |
get_sdk_reference |
Authoritative SDK reference: method argument types per language binding, flags, response schemas, V3→V4 migration mappings. Whenever filter names a method, the response carries that method's callable signature for every binding regardless of topic — so looking up a method's flags also tells you what arguments it takes. Topics: parameters (aliases functions/methods/classes/api/signatures/args), flags, response_schemas, migration, all. Pass language to narrow to your binding. filter accepts any spelling — get entity, get_entity, and getEntity all resolve. topic='flags' with an exact method filter returns a compact one-line-per-flag view; use flag_details (or a single-flag filter) for full definitions. |
find_examples |
Search 37 indexed GitHub repos for working code (Python, Java, C# official; Rust, TypeScript/Node.js community). Three modes: search by query, list files in a repo, or retrieve a specific file. Results include truncation metadata — drill into truncated files with file_path. |
SDK setup & code generation (2 tools)
| Tool | Purpose |
|---|---|
sdk_guide |
Guided SDK setup across 5 platforms (linux_apt, linux_yum, macos_arm, windows, docker) and 5 languages (Python, Java, C# official; Rust, TypeScript/Node.js community). Topics: install, configure, load, export, redo, initialize, search, stewardship, delete, information, error_handling, full_pipeline — with decision trees, anti-patterns, and direct .deb download links for firewalled environments. For load/search/redo, pass record_count to select production-threaded vs single-threaded templates. Optional environment (snowflake, aws_lambda, azure_functions, kafka, spark, or an alias such as lambda/spcs/databricks): pass it when the user says they run on one of these; the response's FIRST field is then environment_note — relay its rules to the user and run its search_docs query before writing code or SQL. Unknown value → is_error listing the valid ones. |
generate_scaffold |
Generates SDK scaffold code from real indexed GitHub snippets with source URLs for provenance. 10 workflows (initialize, configure, add_records, delete, query, redo, stewardship, information, error_handling, full_pipeline) in Python, Java, C#, Rust, or TypeScript/Node.js (V4); Python (V3). Returns multiple snippet variants per workflow. |
Sample data (1 tool)
| Tool | Purpose |
|---|---|
get_sample_data |
Real test data. Three CORD (Collections Of Relatable Data) sets — las-vegas (US, 11 sources), london (international, 5 sources), moscow (Cyrillic, 6 sources) — plus truthset (the Senzing demo truth set: CUSTOMERS, REFERENCE, WATCHLIST — small, pre-mapped, used in quickstarts). Use dataset='list' to discover sets and source='list' to list sources within one. Always present the download_url to the user. |
Reporting & visualization (1 tool)
| Tool | Purpose |
|---|---|
reporting_guide |
Guided reporting and visualization for entity resolution results. Provides SDK patterns for data extraction (Python, Java, C#, Rust, TypeScript/Node.js), SQL analytics queries for aggregate reports, data mart schema (SQLite/PostgreSQL), visualization concepts, and anti-patterns. Topics: export, reports, entity_views, data_mart, dashboard, graph (runnable find_network / find_path traversal calls per binding), quality (precision/recall, split/merge detection, review queues), evaluation (4-point ER evaluation framework). Optional environment (snowflake, aws_lambda, azure_functions, kafka, spark, or an alias such as lambda/spcs/databricks): pass it when the user says they run on one of these; the response's FIRST field is then environment_note — relay its rules to the user and run its search_docs query before writing code or SQL. Unknown value → is_error listing the valid ones. |
Troubleshooting (1 tool)
| Tool | Purpose |
|---|---|
explain_error_code |
Explains any of 450+ Senzing error codes with causes and resolution steps. Accepts SENZ0005, SENZ-0005, 0005, or just 5. |
Meta & utility (2 tools)
| Tool | Purpose |
|---|---|
get_capabilities |
Server version, capabilities overview, available tools, suggested workflows, and getting started guidance. Call this first in any Senzing session. |
submit_feedback |
Two purposes: (1) request a free Senzing evaluation license — set category='license_request' with firstname, work email (personal domains rejected), and optionally lastname/how_heard; a 10-day, 250K-record eval license is emailed. (2) Submit feedback (category = bug/feature/question/general). Always preview the exact message with the user and get explicit confirmation before sending. Never include PII unless the user approves. |
Key workflows
1. Map source data to Senzing format
This is the most common workflow. Follow these steps:
- Call
mapping_workflowwithaction='start', the source file paths and a writableworkspace_dir. A readable file is not required.file_pathsis a label the server records — it never opens the file — so if the user has only described their columns, start anyway using whatever name they used. Never hand-code a mapping because you cannot read the file. When the user names their environment ("we run on Snowflake", "deploying to Lambda"), passenvironmentand relay the returnedenvironment_noterules to them in your reply now. For Snowflake/warehouse tables, export a sample of each table to CSV locally (never paste rows into chat), name each file after its table, and run ONEmapping_workflowover the related tables. - Walk through steps 1–4 (core): Profile → Plan → Map → Generate & Validate.
At step 1 you may run the profiler script, read the data yourself, or
write the
profile_summaryfrom the user's own description of their columns when there is no readable file and no shell. - At each step, pass the
stateobject from the previous response. - Use
analyze_recordto check feature distribution, coverage, and Entity Specification compliance on the output JSON. - Optionally continue steps 5–8 to sandbox-load the mapped data into a fresh SQLite DB — this catches mapping issues the static analyzer misses. This is mapping validation only, not production loading.
- If the analyzer scripts fail to download, use
download_resource.
Tips:
- The workflow generates a mapper script — run it locally to produce JSONL.
- Profile step: read the source data yourself or run the profiler script.
- Plan step: identify master entities vs. child records vs. relationships.
- Map step: map every source field to a Senzing feature with a confidence score.
- Generate & Validate step: emit sample JSON, analyze it, then write and run the mapper before rendering a verdict.
2. Set up the Senzing SDK
- Call
sdk_guidewithtopic='install'— it returns a platform decision tree. - Call again with the chosen platform (e.g.,
topic='install', platform='linux_apt').- For firewalled environments, the response includes
direct_downloadwith.debpackage URLs frommcp.senzing.com/downloads/— no apt repo needed.
- For firewalled environments, the response includes
- Call
sdk_guidewithtopic='configure'for engine configuration code. - Call
sdk_guidewithtopic='load'for record loading code. - Or use
topic='full_pipeline'for install + configure + load + export in one call.
3. Generate SDK integration code
- Call
generate_scaffoldwith the target language and workflow.- Start with
workflow='initialize'for engine setup. - Then
workflow='add_records'for record loading. - Use
workflow='full_pipeline'for an end-to-end example.
- Start with
- Call
find_examplesto find real-world usage patterns. - Use
search_docsfor API details and deployment guidance. - Search flags: do not use the default flags for search — pass the minimal set the
caller needs (
get_sdk_reference(topic='flags')). The default (SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS=..._ALL) includesSZ_ENTITY_INCLUDE_REPRESENTATIVE_FEATURES, which is expensive on large entities (36.7 s vs 1.7 s forSZ_ENTITY_INCLUDE_ALL_FEATURESon one 382-entity search); fetch features only for the few entities that matter.
4. Troubleshoot errors
- Call
explain_error_codewith the code from the user's logs. - Follow the resolution steps in the response.
- Call
search_docsfor additional context on the error class.
5. Evaluate the Senzing SDK
search_docs— learn about architecture (embedded SDK, air-gapped deployment).search_docswith query "pricing" — DSR pricing model.get_sample_data— get real test data (CORD datasets or the pre-mappedtruthset).generate_scaffoldwithworkflow='full_pipeline'— end-to-end example.submit_feedbackwithcategory='license_request'— request a free 10-day, 250K-record evaluation license (preview details with the user first).
6. Migrate v3 to v4
get_sdk_referencewithtopic='migration'— all breaking changes.- Filter by module:
topic='migration', filter='SzEngine'. get_sdk_referencewithtopic='flags'— new flag system (SZ_WITH_INFO replaces WithInfo functions).get_sdk_referencewithtopic='parameters', filter=<method>, language=<yours>— the v4 argument types for each call you are porting.
7. Build entity resolution (ER) reporting
- Call
reporting_guidewithtopic='export'and your language to get data extraction code. - Call
reporting_guidewithtopic='reports'to get SQL for the 4 core aggregate reports. - Call
reporting_guidewithtopic='data_mart'to get the analytical schema and incremental update patterns. - Call
reporting_guidewithtopic='dashboard'for visualization concepts and chart data sources. - Call
reporting_guidewithtopic='graph'for network graph export patterns. - Call
reporting_guidewithtopic='quality'for precision/recall, split/merge detection and review queue strategies. - Call
reporting_guidewithtopic='evaluation'for the 4-point ER evaluation framework with evidence requirements.
8. Check for common pitfalls
Before recommending installation, architecture or deployment approaches:
- Call
search_docswithcategory='anti_patterns'and a query describing what you plan to recommend. - Review any matching anti-patterns before proceeding.
- Note:
sdk_guidealso returns topic-specific anti-patterns inline.
9. Deploy the Senzing SDK
search_docswith your platform (e.g., "docker quickstart", "AWS deployment").search_docsfor database setup (PostgreSQL, MySQL, MSSQL).search_docsfor engine configuration and tuning guidance.generate_scaffoldwithworkflow='initialize'for your language.
Critical rules
These rules are non-negotiable. Violating them produces incorrect output.
- Never hand-code Senzing JSON — use
mapping_workflow. Training data produces wrong attribute names (e.g.,BUSINESS_NAMEvs correctNAME_ORG). - Never guess SDK methods or argument types — use
generate_scaffoldorget_sdk_reference. Methods changed between v3 and v4, and the same method has a different name and different argument types in each binding: Pythonfind_network_by_entity_id(entity_ids: List[int], …), JavafindNetwork(SzEntityIds, …), C#FindNetwork(ISet<long>, …), Rustfind_network_by_entity_id(&[EntityId], …), TypeScriptfindNetwork(number[], …). Never translate a call from one binding to another — callget_sdk_reference(topic='parameters', filter=<method>, language=<yours>)and use the returned signature verbatim. - Check anti-patterns first — before recommending installation or deployment:
search_docs(query="topic", category="anti_patterns"). - MCP first for all Senzing questions —
search_docscovers pricing, architecture, deployment, SDK, database tuning, globalization and more. It reflects current releases — prefer it over training knowledge. - Discover tools dynamically — call
get_capabilitiesrather than assuming tool names from this file or training data.
Best practices
- Always call
get_capabilitiesfirst to get current tool count and workflows. - Prefer
search_docsover web search for any Senzing-related question. The MCP server indexes authoritative content that may not rank well on the web. - Pass state faithfully in
mapping_workflow— the server is stateless, all workflow state lives in the client. - Never send source data to the server. The
analyze_recordtool returns a script that runs locally. The mapping workflow sends field names and schema — not row-level data. - Present
download_urlfromget_sample_dataresults directly to the user. Do not dump raw CORD records into the conversation — they are a preview only. - Version parameter: All tools accept
versionand default to"current"(latest v4). Most tools return current/v4 content regardless of the token passed — for legacy v3 work, rely ongenerate_scaffold(Python v3 is a distinct variant) andget_sdk_reference(topic='migration').
Entity resolution concepts
When discussing the Senzing SDK with users, these terms are important:
- Entity — A real-world person, organization or object represented by one or more records across data sources.
- Feature — A category of matchable identity data: NAME, ADDRESS, PHONE, DOB, SSN, PASSPORT, etc. The Senzing SDK supports 30+ features.
- Attribute — A specific mappable field within a feature (e.g., NAME_ORG and NAME_FULL under NAME; ADDR_LINE1 under ADDRESS). 100+ attributes across the 30+ features.
- Data source — A labeled origin for records (e.g., "CUSTOMERS", "WATCHLIST"). Every record must have a DATA_SOURCE and RECORD_ID.
- RECORD_TYPE — Optional (Recommended) feature that prevents records of different types from resolving together. Standard values: PERSON, ORGANIZATION (watchlists also commonly use VESSEL, AIRCRAFT). Include when known; leave blank if unknown — there is no default.
- Matched — Records confirmed as the same entity.
- Possible match — Records that might be the same entity but need review.
- Relationship — A declared or discovered connection between entities.
- DSR (Data Source Record) — the Senzing subscription pricing unit: one record mapped and loaded into the Senzing SDK, keyed by DATA_SOURCE code + RECORD_ID. Updates and searches are not counted; deletes generally reduce the count.
Examples
Example 1: Map a CSV file
User: "I have a customer CSV at /data/customers.csv I need to load into Senzing"
→ Call mapping_workflow(action='start', file_paths=['/data/customers.csv'], workspace_dir='/data/senzing-work')
→ Walk through core steps 1–4, passing state each time
→ Run analyze_record to check quality and Entity Specification compliance
→ Optionally continue steps 5–8 to sandbox-load into SQLite and validate the mapping
Example 2: Set up the Senzing SDK on Linux
User: "Help me install and set up the Senzing SDK on Ubuntu"
→ Call sdk_guide(topic='install', platform='linux_apt', version='current')
→ Present install commands and engine config
→ If user has firewall issues, use the direct_download URLs from the response
→ Call sdk_guide(topic='configure', platform='linux_apt', language='python', version='current')
→ Present configuration code
Example 3: Generate Python loader code
User: "Write me Python code to initialize Senzing and load records"
→ Call generate_scaffold(language='python', version='current', workflow='initialize')
→ Call generate_scaffold(language='python', version='current', workflow='add_records')
→ Combine and present the code
Example 4: Debug an error
User: "I'm getting SENZ7234 when loading records"
→ Call explain_error_code(error_code='7234', version='current')
→ Present causes and resolution steps
→ Use search_docs if additional context is needed
Files (senzing-mcp-skill)
-
SKILL.md 24.5 KB
--- name: senzing-entity-resolution description: >- Guides AI agents through Senzing entity resolution workflows using the Senzing MCP server. Covers data mapping to Senzing format, SDK code generation (Python, Java, C#, Rust, TypeScript/Node.js), documentation search, error troubleshooting, sample data access, reporting and visualization, SDK setup guides, and V3-to-V4 migration. Use when working with entity resolution, record matching, record linkage, deduplication, Senzing SDK integration, data mapping for Senzing ingestion, or troubleshooting Senzing error codes. Also use when the user mentions matching records across data sources, finding duplicate entities, identity resolution, master data management, or needs to resolve who is who across datasets. license: Proprietary compatibility: Requires Senzing MCP server (https://mcp.senzing.com/mcp) connected via claude mcp add or MCP config metadata: author: senzing version: "1.43.0" --- # Senzing entity resolution — MCP skill Use this skill whenever a task involves entity resolution, record linkage, deduplication or any interaction with the SENZING® SDK. ## What the Senzing SDK is Senzing software provides real time AI powered entity resolution as an embeddable SDK. It determines when two records refer to the same real-world entity (person, organization, etc.) by analyzing names, addresses, identifiers and other attributes across data sources — without training data or manual rules. ## MCP Server Setup The Senzing MCP server is a remote server. Connect it to your client: **Claude Code:** ```bash claude mcp add --transport http senzing https://mcp.senzing.com/mcp ``` **Claude Desktop / Other MCP Clients** — add to your MCP config: ```json { "mcpServers": { "senzing": { "type": "url", "url": "https://mcp.senzing.com/mcp" } } } ``` The server works from pre-fetched documentation — it never connects to live Senzing instances and never handles PII. It also hosts official Senzing SDK `.deb` packages at `/downloads/` for direct download in firewalled environments — `sdk_guide` returns download URLs and install commands automatically. ## Tool reference Start any Senzing session by calling `get_capabilities` for an up-to-date tool listing and suggested workflows. ### Data mapping (3 tools) | Tool | Purpose | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mapping_workflow` | Interactive 8-step workflow. Works with no readable source file: `file_paths` is a label, never opened by the server. Steps 1–4 (core): profile source data → plan entities → map fields → generate & validate. Steps 5–8 (optional): sandbox load into a fresh SQLite DB to catch mapping issues. State is client-side — always pass state back. Requires `workspace_dir` (a writable directory) on `action='start'` — pass it at the top level, or inside `data`; both are accepted. Optional `environment` (`snowflake`, `aws_lambda`, `azure_functions`, `kafka`, `spark`, or an alias such as `lambda`/`spcs`/`databricks`): pass it when the user says they run on one of these; on `start` the response's FIRST field is then `environment_note` — relay its rules to the user and run its `search_docs` query before writing code or SQL. Unknown value → `is_error` listing the valid ones. Dotted `DB.SCHEMA.TABLE` file labels infer `snowflake`. | | `analyze_record` | Returns a Python analyzer script that examines feature distribution, attribute coverage, and data quality, and validates records against the Entity Specification — all locally. No source data is sent. Requires `workspace_dir`. | | `download_resource` | Fallback for fetching workflow resources (analyzer, entity spec, mapping examples) when network restrictions block direct download. Batch-capable: pass `filenames` (array) for multiple resources or `filename` (string) for one. A large file comes back in chunks of at most 36,000 characters carrying `truncated`, `next_offset` and `total_chars` — pass `offset=<next_offset>` to continue; for `.md` reference documents `search_docs` is the cheaper route, and a batch member too large for one chunk is listed under `oversize` (request it alone). | ### Documentation & reference (3 tools) | Tool | Purpose | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search_docs` | Full-text search across entity specification, SDK guides, quickstarts, database tuning, pricing, architecture, globalization, EDA/data analysis, engine configuration, error codes, release notes, and PoC methodology. **Prefer this over web search for any Senzing question.** Use `category='anti_patterns'` to check for known pitfalls before recommending installation, architecture, or deployment approaches. | | `get_sdk_reference` | Authoritative SDK reference: **method argument types per language binding**, flags, response schemas, V3→V4 migration mappings. Whenever `filter` names a method, the response carries that method's callable signature for every binding **regardless of topic** — so looking up a method's flags also tells you what arguments it takes. Topics: `parameters` (aliases `functions`/`methods`/`classes`/`api`/`signatures`/`args`), `flags`, `response_schemas`, `migration`, `all`. Pass `language` to narrow to your binding. `filter` accepts any spelling — `get entity`, `get_entity`, and `getEntity` all resolve. `topic='flags'` with an exact method `filter` returns a compact one-line-per-flag view; use `flag_details` (or a single-flag `filter`) for full definitions. | | `find_examples` | Search 37 indexed GitHub repos for working code (Python, Java, C# official; Rust, TypeScript/Node.js community). Three modes: search by query, list files in a repo, or retrieve a specific file. Results include truncation metadata — drill into truncated files with `file_path`. | ### SDK setup & code generation (2 tools) | Tool | Purpose | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sdk_guide` | Guided SDK setup across 5 platforms (linux_apt, linux_yum, macos_arm, windows, docker) and 5 languages (Python, Java, C# official; Rust, TypeScript/Node.js community). Topics: install, configure, load, export, redo, initialize, search, stewardship, delete, information, error_handling, full_pipeline — with decision trees, anti-patterns, and direct `.deb` download links for firewalled environments. For load/search/redo, pass `record_count` to select production-threaded vs single-threaded templates. Optional `environment` (`snowflake`, `aws_lambda`, `azure_functions`, `kafka`, `spark`, or an alias such as `lambda`/`spcs`/`databricks`): pass it when the user says they run on one of these; the response's FIRST field is then `environment_note` — relay its rules to the user and run its `search_docs` query before writing code or SQL. Unknown value → `is_error` listing the valid ones. | | `generate_scaffold` | Generates SDK scaffold code from real indexed GitHub snippets with source URLs for provenance. 10 workflows (initialize, configure, add_records, delete, query, redo, stewardship, information, error_handling, full_pipeline) in Python, Java, C#, Rust, or TypeScript/Node.js (V4); Python (V3). Returns multiple snippet variants per workflow. | ### Sample data (1 tool) | Tool | Purpose | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_sample_data` | Real test data. Three CORD (Collections Of Relatable Data) sets — las-vegas (US, 11 sources), london (international, 5 sources), moscow (Cyrillic, 6 sources) — plus truthset (the Senzing demo truth set: CUSTOMERS, REFERENCE, WATCHLIST — small, pre-mapped, used in quickstarts). Use `dataset='list'` to discover sets and `source='list'` to list sources within one. Always present the `download_url` to the user. | ### Reporting & visualization (1 tool) | Tool | Purpose | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reporting_guide` | Guided reporting and visualization for entity resolution results. Provides SDK patterns for data extraction (Python, Java, C#, Rust, TypeScript/Node.js), SQL analytics queries for aggregate reports, data mart schema (SQLite/PostgreSQL), visualization concepts, and anti-patterns. Topics: `export`, `reports`, `entity_views`, `data_mart`, `dashboard`, `graph` (runnable `find_network` / `find_path` traversal calls per binding), `quality` (precision/recall, split/merge detection, review queues), `evaluation` (4-point ER evaluation framework). Optional `environment` (`snowflake`, `aws_lambda`, `azure_functions`, `kafka`, `spark`, or an alias such as `lambda`/`spcs`/`databricks`): pass it when the user says they run on one of these; the response's FIRST field is then `environment_note` — relay its rules to the user and run its `search_docs` query before writing code or SQL. Unknown value → `is_error` listing the valid ones. | ### Troubleshooting (1 tool) | Tool | Purpose | | -------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `explain_error_code` | Explains any of 450+ Senzing error codes with causes and resolution steps. Accepts SENZ0005, SENZ-0005, 0005, or just 5. | ### Meta & utility (2 tools) | Tool | Purpose | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_capabilities` | Server version, capabilities overview, available tools, suggested workflows, and getting started guidance. **Call this first in any Senzing session.** | | `submit_feedback` | Two purposes: (1) request a free Senzing evaluation license — set `category='license_request'` with `firstname`, work `email` (personal domains rejected), and optionally `lastname`/`how_heard`; a 10-day, 250K-record eval license is emailed. (2) Submit feedback (`category` = bug/feature/question/general). **Always preview the exact message with the user and get explicit confirmation before sending.** Never include PII unless the user approves. | ## Key workflows ### 1. Map source data to Senzing format This is the most common workflow. Follow these steps: 1. Call `mapping_workflow` with `action='start'`, the source file paths and a writable `workspace_dir`. **A readable file is not required.** `file_paths` is a label the server records — it never opens the file — so if the user has only described their columns, start anyway using whatever name they used. Never hand-code a mapping because you cannot read the file. When the user names their environment ("we run on Snowflake", "deploying to Lambda"), pass `environment` and relay the returned `environment_note` rules to them in your reply now. For Snowflake/warehouse tables, export a sample of each table to CSV locally (never paste rows into chat), name each file after its table, and run ONE `mapping_workflow` over the related tables. 2. Walk through steps 1–4 (core): Profile → Plan → Map → Generate & Validate. At step 1 you may run the profiler script, read the data yourself, **or** write the `profile_summary` from the user's own description of their columns when there is no readable file and no shell. 3. At each step, pass the `state` object from the previous response. 4. Use `analyze_record` to check feature distribution, coverage, and Entity Specification compliance on the output JSON. 5. Optionally continue steps 5–8 to sandbox-load the mapped data into a fresh SQLite DB — this catches mapping issues the static analyzer misses. This is mapping validation only, not production loading. 6. If the analyzer scripts fail to download, use `download_resource`. **Tips:** - The workflow generates a mapper script — run it locally to produce JSONL. - Profile step: read the source data yourself or run the profiler script. - Plan step: identify master entities vs. child records vs. relationships. - Map step: map every source field to a Senzing feature with a confidence score. - Generate & Validate step: emit sample JSON, analyze it, then write and run the mapper before rendering a verdict. ### 2. Set up the Senzing SDK 1. Call `sdk_guide` with `topic='install'` — it returns a platform decision tree. 2. Call again with the chosen platform (e.g., `topic='install', platform='linux_apt'`). - For firewalled environments, the response includes `direct_download` with `.deb` package URLs from `mcp.senzing.com/downloads/` — no apt repo needed. 3. Call `sdk_guide` with `topic='configure'` for engine configuration code. 4. Call `sdk_guide` with `topic='load'` for record loading code. 5. Or use `topic='full_pipeline'` for install + configure + load + export in one call. ### 3. Generate SDK integration code 1. Call `generate_scaffold` with the target language and workflow. - Start with `workflow='initialize'` for engine setup. - Then `workflow='add_records'` for record loading. - Use `workflow='full_pipeline'` for an end-to-end example. 2. Call `find_examples` to find real-world usage patterns. 3. Use `search_docs` for API details and deployment guidance. 4. **Search flags:** do not use the default flags for search — pass the minimal set the caller needs (`get_sdk_reference(topic='flags')`). The default (`SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS` = `..._ALL`) includes `SZ_ENTITY_INCLUDE_REPRESENTATIVE_FEATURES`, which is expensive on large entities (36.7 s vs 1.7 s for `SZ_ENTITY_INCLUDE_ALL_FEATURES` on one 382-entity search); fetch features only for the few entities that matter. ### 4. Troubleshoot errors 1. Call `explain_error_code` with the code from the user's logs. 2. Follow the resolution steps in the response. 3. Call `search_docs` for additional context on the error class. ### 5. Evaluate the Senzing SDK 1. `search_docs` — learn about architecture (embedded SDK, air-gapped deployment). 2. `search_docs` with query "pricing" — DSR pricing model. 3. `get_sample_data` — get real test data (CORD datasets or the pre-mapped `truthset`). 4. `generate_scaffold` with `workflow='full_pipeline'` — end-to-end example. 5. `submit_feedback` with `category='license_request'` — request a free 10-day, 250K-record evaluation license (preview details with the user first). ### 6. Migrate v3 to v4 1. `get_sdk_reference` with `topic='migration'` — all breaking changes. 2. Filter by module: `topic='migration', filter='SzEngine'`. 3. `get_sdk_reference` with `topic='flags'` — new flag system (SZ_WITH_INFO replaces WithInfo functions). 4. `get_sdk_reference` with `topic='parameters', filter=<method>, language=<yours>` — the v4 argument types for each call you are porting. ### 7. Build entity resolution (ER) reporting 1. Call `reporting_guide` with `topic='export'` and your language to get data extraction code. 2. Call `reporting_guide` with `topic='reports'` to get SQL for the 4 core aggregate reports. 3. Call `reporting_guide` with `topic='data_mart'` to get the analytical schema and incremental update patterns. 4. Call `reporting_guide` with `topic='dashboard'` for visualization concepts and chart data sources. 5. Call `reporting_guide` with `topic='graph'` for network graph export patterns. 6. Call `reporting_guide` with `topic='quality'` for precision/recall, split/merge detection and review queue strategies. 7. Call `reporting_guide` with `topic='evaluation'` for the 4-point ER evaluation framework with evidence requirements. ### 8. Check for common pitfalls Before recommending installation, architecture or deployment approaches: 1. Call `search_docs` with `category='anti_patterns'` and a query describing what you plan to recommend. 2. Review any matching anti-patterns before proceeding. 3. Note: `sdk_guide` also returns topic-specific anti-patterns inline. ### 9. Deploy the Senzing SDK 1. `search_docs` with your platform (e.g., "docker quickstart", "AWS deployment"). 2. `search_docs` for database setup (PostgreSQL, MySQL, MSSQL). 3. `search_docs` for engine configuration and tuning guidance. 4. `generate_scaffold` with `workflow='initialize'` for your language. ## Critical rules These rules are non-negotiable. Violating them produces incorrect output. 1. **Never hand-code Senzing JSON** — use `mapping_workflow`. Training data produces wrong attribute names (e.g., `BUSINESS_NAME` vs correct `NAME_ORG`). 2. **Never guess SDK methods or argument types** — use `generate_scaffold` or `get_sdk_reference`. Methods changed between v3 and v4, and the same method has a **different name and different argument types in each binding**: Python `find_network_by_entity_id(entity_ids: List[int], …)`, Java `findNetwork(SzEntityIds, …)`, C# `FindNetwork(ISet<long>, …)`, Rust `find_network_by_entity_id(&[EntityId], …)`, TypeScript `findNetwork(number[], …)`. **Never translate a call from one binding to another** — call `get_sdk_reference(topic='parameters', filter=<method>, language=<yours>)` and use the returned signature verbatim. 3. **Check anti-patterns first** — before recommending installation or deployment: `search_docs(query="topic", category="anti_patterns")`. 4. **MCP first for all Senzing questions** — `search_docs` covers pricing, architecture, deployment, SDK, database tuning, globalization and more. It reflects current releases — prefer it over training knowledge. 5. **Discover tools dynamically** — call `get_capabilities` rather than assuming tool names from this file or training data. ## Best practices - **Always call `get_capabilities` first** to get current tool count and workflows. - **Prefer `search_docs` over web search** for any Senzing-related question. The MCP server indexes authoritative content that may not rank well on the web. - **Pass state faithfully** in `mapping_workflow` — the server is stateless, all workflow state lives in the client. - **Never send source data to the server.** The `analyze_record` tool returns a script that runs locally. The mapping workflow sends field names and schema — not row-level data. - **Present `download_url`** from `get_sample_data` results directly to the user. Do not dump raw CORD records into the conversation — they are a preview only. - **Version parameter:** All tools accept `version` and default to `"current"` (latest v4). Most tools return current/v4 content regardless of the token passed — for legacy v3 work, rely on `generate_scaffold` (Python v3 is a distinct variant) and `get_sdk_reference(topic='migration')`. ## Entity resolution concepts When discussing the Senzing SDK with users, these terms are important: - **Entity** — A real-world person, organization or object represented by one or more records across data sources. - **Feature** — A category of matchable identity data: NAME, ADDRESS, PHONE, DOB, SSN, PASSPORT, etc. The Senzing SDK supports 30+ features. - **Attribute** — A specific mappable field within a feature (e.g., NAME_ORG and NAME_FULL under NAME; ADDR_LINE1 under ADDRESS). 100+ attributes across the 30+ features. - **Data source** — A labeled origin for records (e.g., "CUSTOMERS", "WATCHLIST"). Every record must have a DATA_SOURCE and RECORD_ID. - **RECORD_TYPE** — Optional (Recommended) feature that prevents records of different types from resolving together. Standard values: PERSON, ORGANIZATION (watchlists also commonly use VESSEL, AIRCRAFT). Include when known; leave blank if unknown — there is no default. - **Matched** — Records confirmed as the same entity. - **Possible match** — Records that might be the same entity but need review. - **Relationship** — A declared or discovered connection between entities. - **DSR (Data Source Record)** — the Senzing subscription pricing unit: one record mapped and loaded into the Senzing SDK, keyed by DATA_SOURCE code + RECORD_ID. Updates and searches are not counted; deletes generally reduce the count. ## Examples ### Example 1: Map a CSV file ``` User: "I have a customer CSV at /data/customers.csv I need to load into Senzing" → Call mapping_workflow(action='start', file_paths=['/data/customers.csv'], workspace_dir='/data/senzing-work') → Walk through core steps 1–4, passing state each time → Run analyze_record to check quality and Entity Specification compliance → Optionally continue steps 5–8 to sandbox-load into SQLite and validate the mapping ``` ### Example 2: Set up the Senzing SDK on Linux ``` User: "Help me install and set up the Senzing SDK on Ubuntu" → Call sdk_guide(topic='install', platform='linux_apt', version='current') → Present install commands and engine config → If user has firewall issues, use the direct_download URLs from the response → Call sdk_guide(topic='configure', platform='linux_apt', language='python', version='current') → Present configuration code ``` ### Example 3: Generate Python loader code ``` User: "Write me Python code to initialize Senzing and load records" → Call generate_scaffold(language='python', version='current', workflow='initialize') → Call generate_scaffold(language='python', version='current', workflow='add_records') → Combine and present the code ``` ### Example 4: Debug an error ``` User: "I'm getting SENZ7234 when loading records" → Call explain_error_code(error_code='7234', version='current') → Present causes and resolution steps → Use search_docs if additional context is needed ```
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.