agentreadycrm 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. agentreadycrm-0.1.0/.gitignore +14 -0
  2. agentreadycrm-0.1.0/LICENSE +21 -0
  3. agentreadycrm-0.1.0/PKG-INFO +139 -0
  4. agentreadycrm-0.1.0/README.md +108 -0
  5. agentreadycrm-0.1.0/hatch_build.py +32 -0
  6. agentreadycrm-0.1.0/pyproject.toml +121 -0
  7. agentreadycrm-0.1.0/src/mcp_people/SKILL.md +65 -0
  8. agentreadycrm-0.1.0/src/mcp_people/__init__.py +1 -0
  9. agentreadycrm-0.1.0/src/mcp_people/addresses.py +48 -0
  10. agentreadycrm-0.1.0/src/mcp_people/db/__init__.py +31 -0
  11. agentreadycrm-0.1.0/src/mcp_people/db/dialect.py +395 -0
  12. agentreadycrm-0.1.0/src/mcp_people/db/store.py +7517 -0
  13. agentreadycrm-0.1.0/src/mcp_people/db/tables.py +896 -0
  14. agentreadycrm-0.1.0/src/mcp_people/evidence.py +241 -0
  15. agentreadycrm-0.1.0/src/mcp_people/fields.py +479 -0
  16. agentreadycrm-0.1.0/src/mcp_people/ids.py +106 -0
  17. agentreadycrm-0.1.0/src/mcp_people/keys.py +49 -0
  18. agentreadycrm-0.1.0/src/mcp_people/lifecycle.py +83 -0
  19. agentreadycrm-0.1.0/src/mcp_people/models.py +792 -0
  20. agentreadycrm-0.1.0/src/mcp_people/pipeline.py +86 -0
  21. agentreadycrm-0.1.0/src/mcp_people/query.py +489 -0
  22. agentreadycrm-0.1.0/src/mcp_people/refs.py +64 -0
  23. agentreadycrm-0.1.0/src/mcp_people/runtime.py +239 -0
  24. agentreadycrm-0.1.0/src/mcp_people/server.py +3873 -0
  25. agentreadycrm-0.1.0/src/mcp_people/signal_types.py +60 -0
  26. agentreadycrm-0.1.0/src/mcp_people/skills/people-evidence.md +51 -0
  27. agentreadycrm-0.1.0/src/mcp_people/ui.py +69 -0
  28. agentreadycrm-0.1.0/src/mcp_people_local/__init__.py +6 -0
  29. agentreadycrm-0.1.0/src/mcp_people_local/__main__.py +84 -0
  30. agentreadycrm-0.1.0/src/mcp_people_local/auth.py +99 -0
  31. agentreadycrm-0.1.0/src/mcp_people_local/config.py +44 -0
  32. agentreadycrm-0.1.0/src/mcp_people_local/http.py +72 -0
  33. agentreadycrm-0.1.0/src/mcp_people_local/migrations/env.py +17 -0
  34. agentreadycrm-0.1.0/src/mcp_people_local/migrations/script.py.mako +27 -0
  35. agentreadycrm-0.1.0/src/mcp_people_local/migrations/versions/0001_baseline.py +502 -0
  36. agentreadycrm-0.1.0/src/mcp_people_local/migrations/versions/0002_deleted_at.py +102 -0
  37. agentreadycrm-0.1.0/src/mcp_people_local/migrations/versions/0003_archived_at.py +43 -0
  38. agentreadycrm-0.1.0/src/mcp_people_local/migrations/versions/0004_retire_and_soft_delete_links.py +59 -0
  39. agentreadycrm-0.1.0/src/mcp_people_local/runtime.py +137 -0
  40. agentreadycrm-0.1.0/src/mcp_people_local/schema.py +91 -0
  41. agentreadycrm-0.1.0/src/mcp_people_local/sqlite.py +79 -0
  42. agentreadycrm-0.1.0/ui/dist/index.html +454 -0
@@ -0,0 +1,14 @@
1
+ # Python
2
+ .venv/
3
+ __pycache__/
4
+ *.pyc
5
+ .pytest_cache/
6
+ .ruff_cache/
7
+ # Node
8
+ node_modules/
9
+ # Build output: the wheel and sdist, and the built UI they carry
10
+ dist/
11
+ # The MCP bundle's lock and pack, which a release makes
12
+ mcpb/uv.lock
13
+ *.mcpb
14
+ .env
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 NimbleBrain, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,139 @@
1
+ Metadata-Version: 2.5
2
+ Name: agentreadycrm
3
+ Version: 0.1.0
4
+ Summary: A CRM for AI agents, as an MCP server with views: organizations, contacts, deals and the evidence behind them. Runs locally on one SQLite file.
5
+ Project-URL: Homepage, https://github.com/NimbleBrainInc/agentreadycrm
6
+ Project-URL: Repository, https://github.com/NimbleBrainInc/agentreadycrm.git
7
+ Project-URL: Issues, https://github.com/NimbleBrainInc/agentreadycrm/issues
8
+ Author-email: NimbleBrain Inc <hello@nimblebrain.ai>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: agents,contacts,crm,mcp,mcp-apps,mcp-server,pipeline,sqlite
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Requires-Python: >=3.13
19
+ Requires-Dist: aiosqlite>=0.21
20
+ Requires-Dist: alembic>=1.14
21
+ Requires-Dist: fastmcp<5,>=4
22
+ Requires-Dist: mcp<3,>=2
23
+ Requires-Dist: nimblebrain-server-sdk==0.7.2
24
+ Requires-Dist: pgkeyset==0.2.0
25
+ Requires-Dist: pydantic>=2.12
26
+ Requires-Dist: python-dotenv
27
+ Requires-Dist: sqlalchemy[asyncio]>=2
28
+ Requires-Dist: structlog
29
+ Requires-Dist: uvicorn
30
+ Description-Content-Type: text/markdown
31
+
32
+ # Agent Ready CRM
33
+
34
+ A CRM for AI agents, served as an MCP server: organizations, contacts, interactions, deals,
35
+ and the evidence behind them. An agent resolves a company or a person before it writes, logs
36
+ every touch, moves deals through a pipeline, and records the facts it found with the quote and
37
+ the URL that prove them. A person sees the same records in views that render inside MCP Apps
38
+ hosts.
39
+
40
+ It runs on your own machine: one SQLite file, no account, no cloud service. A hosted service
41
+ at `mcp.agentreadycrm.com`, serving the same tools to a team, is coming soon.
42
+
43
+ ## Install
44
+
45
+ Run it with [uv](https://docs.astral.sh/uv/) (Python 3.13 or later):
46
+
47
+ ```sh
48
+ uvx agentreadycrm
49
+ ```
50
+
51
+ That serves MCP over stdio. To add it to Claude Code:
52
+
53
+ ```sh
54
+ claude mcp add agentreadycrm -- uvx agentreadycrm
55
+ ```
56
+
57
+ For Claude Desktop and other hosts that install MCP bundles, the bundle
58
+ `@nimblebraininc/agentreadycrm` is available from [mpak](https://www.mpak.dev). It runs the
59
+ same package and asks where to keep the database.
60
+
61
+ Any other MCP client that starts a stdio server can run `uvx agentreadycrm` the same way. To
62
+ serve HTTP on `127.0.0.1` instead, run `uvx agentreadycrm --http`; HTTP requires a bearer
63
+ token, which `uvx agentreadycrm --print-token` prints. See [`docs/local.md`](docs/local.md).
64
+
65
+ ## Where your data lives
66
+
67
+ Everything is in one SQLite file, `crm.db`, in your user data directory:
68
+
69
+ | OS | Default location |
70
+ |---|---|
71
+ | macOS | `~/Library/Application Support/agentreadycrm/crm.db` |
72
+ | Linux | `$XDG_DATA_HOME/agentreadycrm/crm.db` (`~/.local/share/...` when unset) |
73
+ | Windows | `%LOCALAPPDATA%\agentreadycrm\crm.db` |
74
+
75
+ Set `PEOPLE_LOCAL_DB` to use another file. Keep it on a local disk, not a network share.
76
+ Several clients may use the same file at once. Upgrades, backups and the HTTP token are
77
+ covered in [`docs/local.md`](docs/local.md).
78
+
79
+ ## Local or hosted
80
+
81
+ | | Local (this package) | Hosted (coming soon) |
82
+ |---|---|---|
83
+ | Runs | On your machine, started by your MCP client | At `mcp.agentreadycrm.com` |
84
+ | Data | One SQLite file you own | A managed Postgres database |
85
+ | Who | One person | A team, each signed in |
86
+ | Tools, views, skills | The same | The same |
87
+
88
+ Both serve the same core: a client sees the same tools, schemas, views and skills, and only
89
+ where identity comes from and where the data lives differ.
90
+
91
+ ## Tools
92
+
93
+ 46 tools, in these families:
94
+
95
+ | Family | Tools |
96
+ |---|---|
97
+ | Resolve and import | `find_or_create_organization`, `find_or_create_contact`, `import_organizations`, `import_contacts` (up to 500 rows a call) |
98
+ | Read and list | `get_contact`, `get_organization`, `get_opportunity`, `list_contacts`, `list_organizations`, `list_opportunities`, `list_interactions`, `count_records`, `resolve_external_refs` |
99
+ | Change | `update_contact`, `update_organization`, `update_opportunity`, `log_interaction` |
100
+ | Duplicates, hide and delete | `merge_contacts`, `merge_organizations`, `archive_contact`, `archive_organization`, `delete_contact`, `delete_organization` |
101
+ | Deals and the pipeline | `create_opportunity`, `move_opportunity`, `get_pipeline`, `define_pipeline_stage`, `update_pipeline_stage` |
102
+ | Custom fields | `define_field`, `update_field`, `list_fields` |
103
+ | Lookalike companies | `link_similar_organizations`, `list_similar_organizations`, `promote_organization` |
104
+ | Evidence: signals | `record_signal`, `withdraw_signal`, `update_signal`, `get_signal`, `list_signals`, `list_signal_types`, `define_signal_type`, `update_signal_type` |
105
+ | Evidence: proof points | `record_proof_point`, `verify_proof_point`, `get_proof_point`, `list_proof_points` |
106
+
107
+ A few rules shape all of them:
108
+
109
+ - **Resolve before you write.** `find_or_create_*` matches by external reference, then domain
110
+ or email, then name, and a match fills only empty fields, so repeating a call converges on
111
+ one record.
112
+ - **Every result carries a `next_step`** telling the agent what to do with it, and every
113
+ failure is one error envelope with a `next_step` that names the fix.
114
+ - **Listings query, they don't walk.** `list_*` take a free-text `query`, a `filter` and
115
+ `sort` on any core, custom, related or rollup field, and `columns`, and page with a cursor.
116
+ - **Nothing is removed.** A delete marks a record so no read finds it; archiving is the
117
+ reversible hide.
118
+
119
+ The server also serves two skills (`skill://people/SKILL.md` and
120
+ `skill://people-evidence/SKILL.md`) with worked examples for hosts that load skills.
121
+
122
+ ## Views
123
+
124
+ Four views, `ui://people/contacts`, `organizations`, `opportunities` and `settings`, render
125
+ in hosts that support [MCP Apps](https://modelcontextprotocol.io/). Each record has an
126
+ address (`people://contacts/<id>` and so on) that a host can open in a view. The views read
127
+ and change data only through the same tools.
128
+
129
+ ## More
130
+
131
+ - [`docs/architecture.md`](docs/architecture.md): runtimes, the data model, deletion and
132
+ archiving, the surface, errors and annotations.
133
+ - [`docs/local.md`](docs/local.md): the database file, several processes, the HTTP token,
134
+ upgrades, backups, and what differs on SQLite.
135
+ - [`CONTRIBUTING.md`](CONTRIBUTING.md): building and testing.
136
+
137
+ ## Licence
138
+
139
+ MIT. See [`LICENSE`](LICENSE).
@@ -0,0 +1,108 @@
1
+ # Agent Ready CRM
2
+
3
+ A CRM for AI agents, served as an MCP server: organizations, contacts, interactions, deals,
4
+ and the evidence behind them. An agent resolves a company or a person before it writes, logs
5
+ every touch, moves deals through a pipeline, and records the facts it found with the quote and
6
+ the URL that prove them. A person sees the same records in views that render inside MCP Apps
7
+ hosts.
8
+
9
+ It runs on your own machine: one SQLite file, no account, no cloud service. A hosted service
10
+ at `mcp.agentreadycrm.com`, serving the same tools to a team, is coming soon.
11
+
12
+ ## Install
13
+
14
+ Run it with [uv](https://docs.astral.sh/uv/) (Python 3.13 or later):
15
+
16
+ ```sh
17
+ uvx agentreadycrm
18
+ ```
19
+
20
+ That serves MCP over stdio. To add it to Claude Code:
21
+
22
+ ```sh
23
+ claude mcp add agentreadycrm -- uvx agentreadycrm
24
+ ```
25
+
26
+ For Claude Desktop and other hosts that install MCP bundles, the bundle
27
+ `@nimblebraininc/agentreadycrm` is available from [mpak](https://www.mpak.dev). It runs the
28
+ same package and asks where to keep the database.
29
+
30
+ Any other MCP client that starts a stdio server can run `uvx agentreadycrm` the same way. To
31
+ serve HTTP on `127.0.0.1` instead, run `uvx agentreadycrm --http`; HTTP requires a bearer
32
+ token, which `uvx agentreadycrm --print-token` prints. See [`docs/local.md`](docs/local.md).
33
+
34
+ ## Where your data lives
35
+
36
+ Everything is in one SQLite file, `crm.db`, in your user data directory:
37
+
38
+ | OS | Default location |
39
+ |---|---|
40
+ | macOS | `~/Library/Application Support/agentreadycrm/crm.db` |
41
+ | Linux | `$XDG_DATA_HOME/agentreadycrm/crm.db` (`~/.local/share/...` when unset) |
42
+ | Windows | `%LOCALAPPDATA%\agentreadycrm\crm.db` |
43
+
44
+ Set `PEOPLE_LOCAL_DB` to use another file. Keep it on a local disk, not a network share.
45
+ Several clients may use the same file at once. Upgrades, backups and the HTTP token are
46
+ covered in [`docs/local.md`](docs/local.md).
47
+
48
+ ## Local or hosted
49
+
50
+ | | Local (this package) | Hosted (coming soon) |
51
+ |---|---|---|
52
+ | Runs | On your machine, started by your MCP client | At `mcp.agentreadycrm.com` |
53
+ | Data | One SQLite file you own | A managed Postgres database |
54
+ | Who | One person | A team, each signed in |
55
+ | Tools, views, skills | The same | The same |
56
+
57
+ Both serve the same core: a client sees the same tools, schemas, views and skills, and only
58
+ where identity comes from and where the data lives differ.
59
+
60
+ ## Tools
61
+
62
+ 46 tools, in these families:
63
+
64
+ | Family | Tools |
65
+ |---|---|
66
+ | Resolve and import | `find_or_create_organization`, `find_or_create_contact`, `import_organizations`, `import_contacts` (up to 500 rows a call) |
67
+ | Read and list | `get_contact`, `get_organization`, `get_opportunity`, `list_contacts`, `list_organizations`, `list_opportunities`, `list_interactions`, `count_records`, `resolve_external_refs` |
68
+ | Change | `update_contact`, `update_organization`, `update_opportunity`, `log_interaction` |
69
+ | Duplicates, hide and delete | `merge_contacts`, `merge_organizations`, `archive_contact`, `archive_organization`, `delete_contact`, `delete_organization` |
70
+ | Deals and the pipeline | `create_opportunity`, `move_opportunity`, `get_pipeline`, `define_pipeline_stage`, `update_pipeline_stage` |
71
+ | Custom fields | `define_field`, `update_field`, `list_fields` |
72
+ | Lookalike companies | `link_similar_organizations`, `list_similar_organizations`, `promote_organization` |
73
+ | Evidence: signals | `record_signal`, `withdraw_signal`, `update_signal`, `get_signal`, `list_signals`, `list_signal_types`, `define_signal_type`, `update_signal_type` |
74
+ | Evidence: proof points | `record_proof_point`, `verify_proof_point`, `get_proof_point`, `list_proof_points` |
75
+
76
+ A few rules shape all of them:
77
+
78
+ - **Resolve before you write.** `find_or_create_*` matches by external reference, then domain
79
+ or email, then name, and a match fills only empty fields, so repeating a call converges on
80
+ one record.
81
+ - **Every result carries a `next_step`** telling the agent what to do with it, and every
82
+ failure is one error envelope with a `next_step` that names the fix.
83
+ - **Listings query, they don't walk.** `list_*` take a free-text `query`, a `filter` and
84
+ `sort` on any core, custom, related or rollup field, and `columns`, and page with a cursor.
85
+ - **Nothing is removed.** A delete marks a record so no read finds it; archiving is the
86
+ reversible hide.
87
+
88
+ The server also serves two skills (`skill://people/SKILL.md` and
89
+ `skill://people-evidence/SKILL.md`) with worked examples for hosts that load skills.
90
+
91
+ ## Views
92
+
93
+ Four views, `ui://people/contacts`, `organizations`, `opportunities` and `settings`, render
94
+ in hosts that support [MCP Apps](https://modelcontextprotocol.io/). Each record has an
95
+ address (`people://contacts/<id>` and so on) that a host can open in a view. The views read
96
+ and change data only through the same tools.
97
+
98
+ ## More
99
+
100
+ - [`docs/architecture.md`](docs/architecture.md): runtimes, the data model, deletion and
101
+ archiving, the surface, errors and annotations.
102
+ - [`docs/local.md`](docs/local.md): the database file, several processes, the HTTP token,
103
+ upgrades, backups, and what differs on SQLite.
104
+ - [`CONTRIBUTING.md`](CONTRIBUTING.md): building and testing.
105
+
106
+ ## Licence
107
+
108
+ MIT. See [`LICENSE`](LICENSE).
@@ -0,0 +1,32 @@
1
+ """Put the built UI inside the core's wheel, so every install serves it.
2
+
3
+ The UI is one inlined HTML file built from ``ui/`` (``cd ui && npm ci && npm run build``). A
4
+ wheel carries it as ``mcp_people/ui_dist/index.html``, where :mod:`mcp_people.ui` finds it with
5
+ no setting and no source checkout. Building a wheel without it fails, so no wheel ships the
6
+ "UI is not built" placeholder. An editable install reads ``ui/dist`` from the source tree
7
+ instead, so it needs no build hook.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from pathlib import Path
13
+ from typing import Any
14
+
15
+ from hatchling.builders.hooks.plugin.interface import BuildHookInterface
16
+
17
+ UI_INDEX = Path("ui") / "dist" / "index.html"
18
+ PACKAGED_AS = "mcp_people/ui_dist/index.html"
19
+
20
+
21
+ class UIBuildHook(BuildHookInterface):
22
+ PLUGIN_NAME = "custom"
23
+
24
+ def initialize(self, version: str, build_data: dict[str, Any]) -> None:
25
+ if self.target_name != "wheel" or version == "editable":
26
+ return
27
+ index = Path(self.root) / UI_INDEX
28
+ if not index.is_file():
29
+ raise FileNotFoundError(
30
+ f"{index} is missing: build the UI first (cd ui && npm ci && npm run build)"
31
+ )
32
+ build_data["force_include"][str(index)] = PACKAGED_AS
@@ -0,0 +1,121 @@
1
+ [project]
2
+ name = "agentreadycrm"
3
+ version = "0.1.0"
4
+ description = "A CRM for AI agents, as an MCP server with views: organizations, contacts, deals and the evidence behind them. Runs locally on one SQLite file."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.13"
9
+ authors = [
10
+ { name = "NimbleBrain Inc", email = "hello@nimblebrain.ai" },
11
+ ]
12
+ keywords = ["mcp", "mcp-server", "mcp-apps", "crm", "contacts", "pipeline", "agents", "sqlite"]
13
+ classifiers = [
14
+ "Development Status :: 4 - Beta",
15
+ "Intended Audience :: Developers",
16
+ "Operating System :: OS Independent",
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3.13",
19
+ "Programming Language :: Python :: 3.14",
20
+ ]
21
+ dependencies = [
22
+ # FastMCP 4 on the MCP SDK v2: serves the 2026-07-28 era and the session-based eras from
23
+ # one server. The ceiling excludes the next major, which removes 4.x compatibility shims.
24
+ "fastmcp>=4,<5",
25
+ "mcp>=2,<3",
26
+ "pydantic>=2.12",
27
+ "sqlalchemy[asyncio]>=2",
28
+ # Annotations, announcements, listing rows, ids, skills and the error contract: the SDK
29
+ # core only, no extras. Pinned exactly: tests/golden/surface.json gates every bump.
30
+ "nimblebrain-server-sdk==0.7.2",
31
+ # Keyset paging. Pinned exactly: tests/test_paging_golden.py holds the cursors agents
32
+ # already hold, so an upgrade is a deliberate, reviewed change.
33
+ "pgkeyset==0.2.0",
34
+ # Structured logs from the core: the access log and the server's own lines.
35
+ "structlog",
36
+ # The server reads a .env beside it when one exists.
37
+ "python-dotenv",
38
+ # The local runtime: SQLite through aiosqlite, its schema history through Alembic, and
39
+ # local HTTP (agentreadycrm --http) through uvicorn.
40
+ "aiosqlite>=0.21",
41
+ "alembic>=1.14",
42
+ "uvicorn",
43
+ ]
44
+
45
+ [project.urls]
46
+ Homepage = "https://github.com/NimbleBrainInc/agentreadycrm"
47
+ Repository = "https://github.com/NimbleBrainInc/agentreadycrm.git"
48
+ Issues = "https://github.com/NimbleBrainInc/agentreadycrm/issues"
49
+
50
+ [project.scripts]
51
+ agentreadycrm = "mcp_people_local.__main__:main"
52
+
53
+ # The runtimes register here; PEOPLE_RUNTIME names the one a process serves.
54
+ [project.entry-points."mcp_people.runtimes"]
55
+ local = "mcp_people_local.runtime:LocalRuntime"
56
+
57
+ [build-system]
58
+ requires = ["hatchling>=1.27"]
59
+ build-backend = "hatchling.build"
60
+
61
+ [tool.hatch.build.targets.wheel]
62
+ packages = ["src/mcp_people", "src/mcp_people_local"]
63
+
64
+ # Packs the built UI (ui/dist/index.html) into the wheel as mcp_people/ui_dist/index.html, and
65
+ # refuses to build a wheel without it.
66
+ [tool.hatch.build.targets.wheel.hooks.custom]
67
+ path = "hatch_build.py"
68
+
69
+ # The sdist carries the built UI, so a wheel built from it (pip, uv) packs the same views.
70
+ # It is a build output (ui/ is gitignored there), so it is named here, not found through git.
71
+ [tool.hatch.build.targets.sdist]
72
+ include = [
73
+ "/src",
74
+ "/ui/dist/index.html",
75
+ "/hatch_build.py",
76
+ "/README.md",
77
+ "/LICENSE",
78
+ ]
79
+ artifacts = ["/ui/dist/index.html"]
80
+
81
+ [tool.ruff]
82
+ target-version = "py313"
83
+ line-length = 100
84
+
85
+ [tool.ruff.lint]
86
+ select = [
87
+ "E", # pycodestyle errors
88
+ "W", # pycodestyle warnings
89
+ "F", # pyflakes
90
+ "I", # isort
91
+ "B", # flake8-bugbear
92
+ "C4", # flake8-comprehensions
93
+ "UP", # pyupgrade
94
+ ]
95
+ ignore = [
96
+ "E501", # line too long - handled by formatter
97
+ "B008", # do not perform function calls in argument defaults
98
+ ]
99
+
100
+ [tool.ruff.lint.isort]
101
+ known-first-party = ["mcp_people", "mcp_people_local"]
102
+
103
+ [tool.ruff.format]
104
+ quote-style = "double"
105
+ indent-style = "space"
106
+
107
+ [tool.pytest.ini_options]
108
+ asyncio_mode = "auto"
109
+ asyncio_default_fixture_loop_scope = "function"
110
+ testpaths = ["tests"]
111
+
112
+ [dependency-groups]
113
+ dev = [
114
+ "pytest>=8.4.2",
115
+ "pytest-asyncio>=0.24.0",
116
+ "pyyaml>=6",
117
+ "ruff>=0.13.1",
118
+ # Exact: each ty release adds diagnostics, so a lock refresh would fail typecheck on code
119
+ # it did not touch. Move it on purpose, with the fixes it asks for.
120
+ "ty==0.0.49",
121
+ ]
@@ -0,0 +1,65 @@
1
+ ---
2
+ name: people
3
+ description: Working the CRM well beyond the server's rules - examples of resolving, importing, filtering and counting, external references, and what to do when a field is missing. Read when a task spans several records or a list.
4
+ metadata:
5
+ nimblebrain:
6
+ loading-strategy: dynamic
7
+ tool-affinity:
8
+ - find_or_create_contact
9
+ - find_or_create_organization
10
+ - import_contacts
11
+ - import_organizations
12
+ - resolve_external_refs
13
+ - list_contacts
14
+ - list_organizations
15
+ - count_records
16
+ - update_contact
17
+ - update_organization
18
+ - define_field
19
+ - merge_contacts
20
+ - merge_organizations
21
+ ---
22
+
23
+ # Working the CRM
24
+
25
+ The server's instructions hold the rules (resolve before you write, field or dossier,
26
+ query rather than walk). This adds the patterns behind them.
27
+
28
+ ## Bringing records in
29
+
30
+ - One person or company: `find_or_create_*` with everything you know in one call.
31
+ - A list: `import_contacts` / `import_organizations`, up to 500 rows a call. Rows that fail
32
+ come back under `skipped` with their index; fix those and import them again, since the
33
+ rest are saved and a repeat changes nothing.
34
+ - From another system: put its id for each record in `external_refs` as a URI
35
+ (`crm://companies/123`, or its record URL), never in a field. Before fetching from the
36
+ source, `resolve_external_refs` says which references are already here, so you fetch only
37
+ the missing ones.
38
+
39
+ ## Filtering and counting
40
+
41
+ People at strong-fit companies with a live signal and a valid email:
42
+
43
+ ```json
44
+ {"and": [
45
+ {"field": "organization.fit", "op": "eq", "value": "strong"},
46
+ {"field": "signals.active", "op": "gte", "value": 1},
47
+ {"field": "email_status", "op": "eq", "value": "valid"}
48
+ ]}
49
+ ```
50
+
51
+ "How many strong-fit companies, by industry" is one `count_records(entity="organization",
52
+ field="industry", filter=...)`, not a walk. A refused filter names the paths, operators and
53
+ options that would have worked; use them rather than guessing again. Pass `columns` whenever
54
+ you read more than one page.
55
+
56
+ ## When a field is missing
57
+
58
+ If the field you need is not in `list_fields` and you cannot define it, tell the user which
59
+ field is missing. Do not store the value in a dossier or another field meanwhile: it could
60
+ not be filtered, and the next agent would not find it.
61
+
62
+ ## Showing a record
63
+
64
+ To show someone a contact, organization or deal, open the CRM at the record's `uri` (with
65
+ the host's open-app tool, where it has one) rather than describing where to click.
@@ -0,0 +1 @@
1
+ """People MCP Server."""
@@ -0,0 +1,48 @@
1
+ """The address of each record People holds that another tool may cite: a resource URI.
2
+
3
+ A contact, an organization, an opportunity, a signal and a proof point each have one, and
4
+ it is the same value everywhere it appears: the ``uri`` on every record a tool returns and
5
+ the resource this server serves at it. Another tool cites a People record by this address
6
+ and never by its id, because the address names the system that holds it and the id does
7
+ not. The first three are also the step the UI reports to the host as its location,
8
+ so the host can open the view showing them; a signal and a
9
+ proof point have no view, only the resource.
10
+
11
+ The kind is in the id's prefix (``ct_`` / ``org_`` / ``op_`` / ``sg_`` / ``pp_``,
12
+ :mod:`mcp_people.ids`), so the address is a pure function of the id. The UI parses the
13
+ three view shapes (``ui/src/App.tsx``); ``test_addresses.py`` pins them all on this side.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from mcp_people.ids import (
19
+ CONTACT_PREFIX,
20
+ OPPORTUNITY_PREFIX,
21
+ ORG_PREFIX,
22
+ PROOF_POINT_PREFIX,
23
+ SIGNAL_PREFIX,
24
+ )
25
+
26
+ CONTACT_URI_TEMPLATE = "people://contacts/{contact_id}"
27
+ ORGANIZATION_URI_TEMPLATE = "people://organizations/{organization_id}"
28
+ OPPORTUNITY_URI_TEMPLATE = "people://opportunities/{opportunity_id}"
29
+ SIGNAL_URI_TEMPLATE = "people://signals/{signal_id}"
30
+ PROOF_POINT_URI_TEMPLATE = "people://proof-points/{proof_point_id}"
31
+
32
+ _COLLECTION_BY_PREFIX = {
33
+ CONTACT_PREFIX: "contacts",
34
+ ORG_PREFIX: "organizations",
35
+ OPPORTUNITY_PREFIX: "opportunities",
36
+ SIGNAL_PREFIX: "signals",
37
+ PROOF_POINT_PREFIX: "proof-points",
38
+ }
39
+
40
+
41
+ def record_uri(record_id: str) -> str | None:
42
+ """The address of the record ``record_id`` names.
43
+
44
+ ``None`` for an id of a kind no other tool cites (an interaction, an edge).
45
+ """
46
+ prefix, _, body = record_id.partition("_")
47
+ collection = _COLLECTION_BY_PREFIX.get(prefix)
48
+ return f"people://{collection}/{record_id}" if collection and body else None
@@ -0,0 +1,31 @@
1
+ """People database layer.
2
+
3
+ Re-exports the SQLAlchemy ``metadata`` and table objects so callers (store,
4
+ migrations, tests) can ``from mcp_people.db import metadata, contact`` without
5
+ reaching into ``tables`` directly. Sessions come from the runtime
6
+ (:meth:`mcp_people.runtime.Runtime.session`), not from here.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from mcp_people.db.tables import (
12
+ contact,
13
+ interaction,
14
+ metadata,
15
+ opportunity,
16
+ organization,
17
+ people_audit,
18
+ uq_contact_email,
19
+ uq_org_domain,
20
+ )
21
+
22
+ __all__ = [
23
+ "metadata",
24
+ "organization",
25
+ "contact",
26
+ "interaction",
27
+ "opportunity",
28
+ "people_audit",
29
+ "uq_contact_email",
30
+ "uq_org_domain",
31
+ ]