capsulemcp 1.0.0 → 1.0.1

package/README.md

@@ -1,5 +1,7 @@
 # capsulemcp
 
+[![capsulemcp MCP server](https://glama.ai/mcp/servers/soil-dev/capsulemcp/badges/score.svg)](https://glama.ai/mcp/servers/soil-dev/capsulemcp)
+
 A [Model Context Protocol](https://modelcontextprotocol.io) server for [Capsule CRM](https://capsulecrm.com). Connect Claude (Desktop, Code, or web Projects via Custom Connector) to your CRM and let it answer natural-language questions across the full record graph: contacts, organisations, opportunities, projects, tasks, and timeline activity. Beyond the basics it covers structured filters with field/operator conditions, saved searches with sort, workflow tracks (templates and instances), file attachments (read + write), audit of deleted records, and batch fetches up to 10 records per call.
 
 - **81 tools** across the Capsule resource graph (49 in read-only mode) — full read coverage plus careful, confirm-gated writes
@@ -31,7 +33,7 @@ For most individual users the install is a single JSON snippet pasted into Claud
      "mcpServers": {
        "capsule": {
          "command": "npx",
-         "args": ["-y", "github:soil-dev/capsulemcp#v1.0.0"],
+         "args": ["-y", "capsulemcp"],
          "env": {
            "CAPSULE_API_TOKEN": "<paste token here>",
            "CAPSULE_MCP_READONLY": "1"
@@ -43,7 +45,7 @@ For most individual users the install is a single JSON snippet pasted into Claud
 
 3. Restart Claude Desktop. The Capsule tools appear in the tool picker.
 
-That's it. The first launch takes ~30 seconds while npx clones and builds; subsequent launches are fast. See [INSTALL.md](INSTALL.md) for the Claude Code path, manual install, and troubleshooting.
+That's it. The first launch fetches the package from npm (a few seconds); subsequent launches are instant from the npx cache. To pin a specific version, use `"capsulemcp@1.0.1"` in `args`. If you're tracking a fork or an unreleased branch, use the GitHub-ref form instead: `"github:soil-dev/capsulemcp#v1.0.1"` — same arguments, just installs from a git clone rather than the npm registry. See [INSTALL.md](INSTALL.md) for the Claude Code path, manual install, and troubleshooting.
 
 ## Tools
 

package/dist/http.js

@@ -979,8 +979,8 @@ function validateWebsiteAddress(data, ctx) {
     return;
   }
   const parsed = new URL(data.address);
-  const BLOCKED = /* @__PURE__ */ new Set(["javascript:", "data:", "vbscript:"]);
-  if (BLOCKED.has(parsed.protocol)) {
+  const ALLOWED_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
+  if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
     ctx.addIssue({
       code: "custom",
       path: ["address"],
@@ -2395,7 +2395,7 @@ function createCapsuleMcpServer() {
   const readOnly = isReadOnly();
   const server = new McpServer({
     name: "capsulemcp",
-    version: "1.0.0",
+    version: "1.0.1",
     description: "Read and (optionally) modify Capsule CRM data \u2014 parties, opportunities, projects, tasks, timeline entries, pipelines, tags.",
     websiteUrl: "https://github.com/soil-dev/capsulemcp",
     icons: ICONS
@@ -2431,14 +2431,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "list_party_opportunities",
-    "List all opportunities linked to a given party.",
+    "List opportunities linked to a given party. Returns the same record shape as get_opportunity, filtered to one party \u2014 use this to answer 'what deals do we have with X?' without enumerating all opportunities. Accepts optional embed (e.g. 'tags,fields') to include those in one round-trip.",
     listPartyOpportunitiesSchema,
     listPartyOpportunities
   );
   registerTool(
     server,
     "list_party_projects",
-    "List all projects (cases) linked to a given party.",
+    "List projects (cases) linked to a given party. Returns the same record shape as get_project, filtered to one party \u2014 use this to answer 'what cases is X involved in?' without enumerating all projects. Accepts optional embed (e.g. 'tags,fields'). For the opportunity-side analogue, use list_party_opportunities.",
     listPartyProjectsSchema,
     listPartyProjects
   );
@@ -2566,7 +2566,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "get_opportunity",
-    "Fetch a single opportunity by its numeric ID.",
+    "Fetch a single opportunity by its numeric id. Returns the full record including value, milestone, owner, party, and any embedded tags/custom fields. Use embed='tags,fields' to include those in one round-trip. For batch fetches of up to 10 opportunities at once, use get_opportunities instead.",
     getOpportunitySchema,
     getOpportunity
   );
@@ -2594,7 +2594,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "list_associated_projects",
-    "List projects (cases) associated with a given opportunity. The inverse direction (project \u2192 opportunity) is on each project's `opportunity` field directly.",
+    "List projects (cases) associated with a given opportunity. Returns the same record shape as list_projects, filtered to one opportunity. The inverse direction (project \u2192 opportunity) is on each project's `opportunity` field directly, so this tool is only needed for opportunity \u2192 projects discovery \u2014 use list_party_projects for party \u2192 projects.",
     listAssociatedProjectsSchema,
     listAssociatedProjects
   );
@@ -2602,7 +2602,7 @@ function createCapsuleMcpServer() {
     registerTool(
       server,
       "create_opportunity",
-      "Create a new opportunity linked to a party and a pipeline milestone.",
+      "Create a new opportunity linked to a party. Requires partyId and milestoneId (which pins the deal to a specific pipeline stage \u2014 pipeline is inferred from the milestone). Value is optional but if amount is set, currency must be set too (3-letter ISO 4217 code, e.g. 'USD'). Discover valid milestone ids via list_pipelines + list_milestones first. For multi-party deals, use add_additional_party after creation.",
       createOpportunitySchema,
       createOpportunity
     );
@@ -2660,7 +2660,7 @@ function createCapsuleMcpServer() {
     registerTool(
       server,
       "create_project",
-      "Create a new project (case) in Capsule CRM linked to a party.",
+      "Create a new project (case) in Capsule CRM linked to a party. Requires partyId and name; description, status, owner, and starting board/stage are optional. To pin a project to a specific board+stage on creation, pass stageId (which uniquely identifies a stage within a board). Discover valid ids via list_boards + list_stages. Returns the created project including its assigned id.",
       createProjectSchema,
       createProject
     );
@@ -2724,7 +2724,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "get_task",
-    "Fetch a single task by its numeric ID.",
+    "Fetch a single task by its numeric id. Returns the task's description, due date, owner, completion state, and the entity it's attached to (party / opportunity / project, if any \u2014 standalone tasks not tied to a record are also valid). For batch fetches of up to 10 tasks at once, use get_tasks instead.",
     getTaskSchema,
     getTask
   );
@@ -2775,14 +2775,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "list_opportunity_entries",
-    "List timeline entries (notes, captured emails, completed-task records) for an opportunity.",
+    "List timeline entries (notes, captured emails, completed-task records) for an opportunity. Returns entries newest-first. Each entry has a type ('note', 'email', 'task'), free-text content, and timestamps. Use this to answer 'what's the latest on deal X?' For party or project timelines, use list_party_entries or list_project_entries respectively.",
     listOpportunityEntriesSchema,
     listOpportunityEntries
   );
   registerTool(
     server,
     "list_project_entries",
-    "List timeline entries (notes, captured emails, completed-task records) for a project (case).",
+    "List timeline entries (notes, captured emails, completed-task records) for a project (case). Returns entries newest-first. Each entry has a type ('note', 'email', 'task'), free-text content, and timestamps. Use this to answer 'what's the latest on case X?' For party or opportunity timelines, use list_party_entries or list_opportunity_entries respectively.",
     listProjectEntriesSchema,
     listProjectEntries
   );
@@ -2910,21 +2910,21 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "list_pipelines",
-    "List all sales pipelines defined in Capsule CRM.",
+    "List all sales pipelines defined in Capsule CRM. Returns each pipeline's id, name, and milestones (deal stages, ordered by position). Use this to discover the pipelineId when creating an opportunity, then pick a milestone from the same pipeline via list_milestones. Pipelines are stable per Capsule account \u2014 list once and cache; they rarely change.",
     listPipelinesSchema,
     listPipelines
   );
   registerTool(
     server,
     "list_milestones",
-    "List all milestones (stages) within a specific opportunity pipeline.",
+    "List milestones (deal stages) within a specific opportunity pipeline. Returns each milestone's id, name, probability, and position. Used when creating opportunities (pass milestoneId to create_opportunity) or moving them across stages (set milestoneId in update_opportunity). Discover the pipelineId first via list_pipelines. Milestones are pipeline-scoped \u2014 not interchangeable across pipelines.",
     listMilestonesSchema,
     listMilestones
   );
   registerTool(
     server,
     "list_boards",
-    "List all project (kase) boards defined in Capsule. A board is a grouping of stages that projects flow through \u2014 the project equivalent of an opportunity pipeline.",
+    "List all project (case) boards defined in Capsule. A board is a grouping of stages that projects flow through \u2014 the project equivalent of an opportunity pipeline. Returns each board's id, name, and stages. Use this to discover boardId when creating a project, then pick a starting stage via list_stages. Like pipelines, boards are stable per account.",
     listBoardsSchema,
     listBoards
   );
@@ -2952,7 +2952,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "list_activitytypes",
-    "List all configured activity types (e.g. Call, Meeting, Email). These are the categories used when logging timeline entries.",
+    "List all configured activity types (e.g. Call, Meeting, Email). These are the categories used when logging timeline entries via add_note. Returns each type's id and name. The set is account-configured rather than a fixed enum, so call this to discover valid values before referencing an activityType in entry creation.",
     listActivityTypesSchema,
     listActivityTypes
   );
@@ -3015,7 +3015,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "list_tags",
-    "List all tags available for a given entity type (parties, opportunities, or kases).",
+    "List all tags available for a given entity type (parties, opportunities, or kases). Returns each tag's id, name, and any data-tag field schema. Tags are entity-specific \u2014 a party tag is not interchangeable with an opportunity tag. Use this to discover valid tag ids before calling add_tag, or to display the tag catalogue to the user when they ask 'what tags do we use?'",
     listTagsSchema,
     listTags
   );
@@ -3038,7 +3038,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server,
     "list_users",
-    "List all users in the Capsule account.",
+    "List all users in the Capsule account. Returns each user's id, username, optional first/last name, role, and party reference. Some users may have null first/last name fields (only username set) \u2014 fall back to username for display. Use this to discover user ids for owner-filtered queries against opportunities, projects, and tasks, or to map a user to their party record via user.party.id.",
     listUsersSchema,
     listUsers
   );

package/dist/index.js

@@ -499,8 +499,8 @@ function validateWebsiteAddress(data, ctx) {
     return;
   }
   const parsed = new URL(data.address);
-  const BLOCKED = /* @__PURE__ */ new Set(["javascript:", "data:", "vbscript:"]);
-  if (BLOCKED.has(parsed.protocol)) {
+  const ALLOWED_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
+  if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
     ctx.addIssue({
       code: "custom",
       path: ["address"],
@@ -1915,7 +1915,7 @@ function createCapsuleMcpServer() {
   const readOnly = isReadOnly();
   const server2 = new McpServer({
     name: "capsulemcp",
-    version: "1.0.0",
+    version: "1.0.1",
     description: "Read and (optionally) modify Capsule CRM data \u2014 parties, opportunities, projects, tasks, timeline entries, pipelines, tags.",
     websiteUrl: "https://github.com/soil-dev/capsulemcp",
     icons: ICONS
@@ -1951,14 +1951,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "list_party_opportunities",
-    "List all opportunities linked to a given party.",
+    "List opportunities linked to a given party. Returns the same record shape as get_opportunity, filtered to one party \u2014 use this to answer 'what deals do we have with X?' without enumerating all opportunities. Accepts optional embed (e.g. 'tags,fields') to include those in one round-trip.",
     listPartyOpportunitiesSchema,
     listPartyOpportunities
   );
   registerTool(
     server2,
     "list_party_projects",
-    "List all projects (cases) linked to a given party.",
+    "List projects (cases) linked to a given party. Returns the same record shape as get_project, filtered to one party \u2014 use this to answer 'what cases is X involved in?' without enumerating all projects. Accepts optional embed (e.g. 'tags,fields'). For the opportunity-side analogue, use list_party_opportunities.",
     listPartyProjectsSchema,
     listPartyProjects
   );
@@ -2086,7 +2086,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "get_opportunity",
-    "Fetch a single opportunity by its numeric ID.",
+    "Fetch a single opportunity by its numeric id. Returns the full record including value, milestone, owner, party, and any embedded tags/custom fields. Use embed='tags,fields' to include those in one round-trip. For batch fetches of up to 10 opportunities at once, use get_opportunities instead.",
     getOpportunitySchema,
     getOpportunity
   );
@@ -2114,7 +2114,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "list_associated_projects",
-    "List projects (cases) associated with a given opportunity. The inverse direction (project \u2192 opportunity) is on each project's `opportunity` field directly.",
+    "List projects (cases) associated with a given opportunity. Returns the same record shape as list_projects, filtered to one opportunity. The inverse direction (project \u2192 opportunity) is on each project's `opportunity` field directly, so this tool is only needed for opportunity \u2192 projects discovery \u2014 use list_party_projects for party \u2192 projects.",
     listAssociatedProjectsSchema,
     listAssociatedProjects
   );
@@ -2122,7 +2122,7 @@ function createCapsuleMcpServer() {
     registerTool(
       server2,
       "create_opportunity",
-      "Create a new opportunity linked to a party and a pipeline milestone.",
+      "Create a new opportunity linked to a party. Requires partyId and milestoneId (which pins the deal to a specific pipeline stage \u2014 pipeline is inferred from the milestone). Value is optional but if amount is set, currency must be set too (3-letter ISO 4217 code, e.g. 'USD'). Discover valid milestone ids via list_pipelines + list_milestones first. For multi-party deals, use add_additional_party after creation.",
       createOpportunitySchema,
       createOpportunity
     );
@@ -2180,7 +2180,7 @@ function createCapsuleMcpServer() {
     registerTool(
       server2,
       "create_project",
-      "Create a new project (case) in Capsule CRM linked to a party.",
+      "Create a new project (case) in Capsule CRM linked to a party. Requires partyId and name; description, status, owner, and starting board/stage are optional. To pin a project to a specific board+stage on creation, pass stageId (which uniquely identifies a stage within a board). Discover valid ids via list_boards + list_stages. Returns the created project including its assigned id.",
       createProjectSchema,
       createProject
     );
@@ -2244,7 +2244,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "get_task",
-    "Fetch a single task by its numeric ID.",
+    "Fetch a single task by its numeric id. Returns the task's description, due date, owner, completion state, and the entity it's attached to (party / opportunity / project, if any \u2014 standalone tasks not tied to a record are also valid). For batch fetches of up to 10 tasks at once, use get_tasks instead.",
     getTaskSchema,
     getTask
   );
@@ -2295,14 +2295,14 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "list_opportunity_entries",
-    "List timeline entries (notes, captured emails, completed-task records) for an opportunity.",
+    "List timeline entries (notes, captured emails, completed-task records) for an opportunity. Returns entries newest-first. Each entry has a type ('note', 'email', 'task'), free-text content, and timestamps. Use this to answer 'what's the latest on deal X?' For party or project timelines, use list_party_entries or list_project_entries respectively.",
     listOpportunityEntriesSchema,
     listOpportunityEntries
   );
   registerTool(
     server2,
     "list_project_entries",
-    "List timeline entries (notes, captured emails, completed-task records) for a project (case).",
+    "List timeline entries (notes, captured emails, completed-task records) for a project (case). Returns entries newest-first. Each entry has a type ('note', 'email', 'task'), free-text content, and timestamps. Use this to answer 'what's the latest on case X?' For party or opportunity timelines, use list_party_entries or list_opportunity_entries respectively.",
     listProjectEntriesSchema,
     listProjectEntries
   );
@@ -2430,21 +2430,21 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "list_pipelines",
-    "List all sales pipelines defined in Capsule CRM.",
+    "List all sales pipelines defined in Capsule CRM. Returns each pipeline's id, name, and milestones (deal stages, ordered by position). Use this to discover the pipelineId when creating an opportunity, then pick a milestone from the same pipeline via list_milestones. Pipelines are stable per Capsule account \u2014 list once and cache; they rarely change.",
     listPipelinesSchema,
     listPipelines
   );
   registerTool(
     server2,
     "list_milestones",
-    "List all milestones (stages) within a specific opportunity pipeline.",
+    "List milestones (deal stages) within a specific opportunity pipeline. Returns each milestone's id, name, probability, and position. Used when creating opportunities (pass milestoneId to create_opportunity) or moving them across stages (set milestoneId in update_opportunity). Discover the pipelineId first via list_pipelines. Milestones are pipeline-scoped \u2014 not interchangeable across pipelines.",
     listMilestonesSchema,
     listMilestones
   );
   registerTool(
     server2,
     "list_boards",
-    "List all project (kase) boards defined in Capsule. A board is a grouping of stages that projects flow through \u2014 the project equivalent of an opportunity pipeline.",
+    "List all project (case) boards defined in Capsule. A board is a grouping of stages that projects flow through \u2014 the project equivalent of an opportunity pipeline. Returns each board's id, name, and stages. Use this to discover boardId when creating a project, then pick a starting stage via list_stages. Like pipelines, boards are stable per account.",
     listBoardsSchema,
     listBoards
   );
@@ -2472,7 +2472,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "list_activitytypes",
-    "List all configured activity types (e.g. Call, Meeting, Email). These are the categories used when logging timeline entries.",
+    "List all configured activity types (e.g. Call, Meeting, Email). These are the categories used when logging timeline entries via add_note. Returns each type's id and name. The set is account-configured rather than a fixed enum, so call this to discover valid values before referencing an activityType in entry creation.",
     listActivityTypesSchema,
     listActivityTypes
   );
@@ -2535,7 +2535,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "list_tags",
-    "List all tags available for a given entity type (parties, opportunities, or kases).",
+    "List all tags available for a given entity type (parties, opportunities, or kases). Returns each tag's id, name, and any data-tag field schema. Tags are entity-specific \u2014 a party tag is not interchangeable with an opportunity tag. Use this to discover valid tag ids before calling add_tag, or to display the tag catalogue to the user when they ask 'what tags do we use?'",
     listTagsSchema,
     listTags
   );
@@ -2558,7 +2558,7 @@ function createCapsuleMcpServer() {
   registerTool(
     server2,
     "list_users",
-    "List all users in the Capsule account.",
+    "List all users in the Capsule account. Returns each user's id, username, optional first/last name, role, and party reference. Some users may have null first/last name fields (only username set) \u2014 fall back to username for display. Use this to discover user ids for owner-filtered queries against opportunities, projects, and tasks, or to map a user to their party record via user.party.id.",
     listUsersSchema,
     listUsers
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capsulemcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Model Context Protocol server for Capsule CRM. Lets Claude (Desktop, Code, or web Projects via Custom Connector) read and write your CRM in plain English. Covers contacts, opportunities, projects, tasks, timeline activity, structured filters, saved filters with sort, workflow tracks, file attachments, audit, and batch fetches.",
   "keywords": [
     "mcp",