{"_id":"@ainative/skill-mcp-development","name":"@ainative/skill-mcp-development","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@ainative/skill-mcp-development","version":"1.0.0","description":"MCP server development patterns extending Anthropic's mcp-builder with AINative-specific conventions for building tool-based AI systems","keywords":["ainative","skill","mcp","model-context-protocol","zerodb","tools","server-development","ai-agents"],"author":{"name":"AINative Studio"},"license":"MIT","homepage":"https://ainative.studio/skills/mcp-development","repository":{"type":"git","url":"git+https://github.com/AINative-Studio/ainative-skills.git","directory":"skills/mcp-development"},"bugs":{"url":"https://github.com/AINative-Studio/ainative-skills/issues"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"peerDependencies":{"@modelcontextprotocol/sdk":"^0.5.0","zod":"^3.22.0"},"devDependencies":{"@types/node":"^20.0.0"},"_id":"@ainative/skill-mcp-development@1.0.0","gitHead":"6b796cac1c2fb43072eca570f442dd40a55c8cd9","_nodeVersion":"22.21.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-H6wOwSXtqwUwb1CsDVAA3sp5K19st6+mP99uxzEejOrUiSiWRwqRzmpYrnaXELpEovxUQYYj5kq+GWaQRWh9vw==","shasum":"50c9698e8e317e592d07cd44ba8f034f22ed1e11","tarball":"https://registry.npmjs.org/@ainative/skill-mcp-development/-/skill-mcp-development-1.0.0.tgz","fileCount":7,"unpackedSize":58571,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDcZVuvPdt0ZXxTsk/9DvHukDvsBYEzbAE9YGdcF2N2EgIhAP3z9Tahd4SU9MYGRc0eScnuY6d7t/3YCp9QGJI+18QG"}]},"_npmUser":{"name":"ainative-studio","email":"toby@rely.ventures"},"directories":{},"maintainers":[{"name":"ainative-studio","email":"toby@rely.ventures"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/skill-mcp-development_1.0.0_1767773582470_0.23823235840873425"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-07T08:13:02.381Z","1.0.0":"2026-01-07T08:13:02.616Z","modified":"2026-01-07T08:13:02.918Z"},"maintainers":[{"name":"ainative-studio","email":"toby@rely.ventures"}],"description":"MCP server development patterns extending Anthropic's mcp-builder with AINative-specific conventions for building tool-based AI systems","homepage":"https://ainative.studio/skills/mcp-development","keywords":["ainative","skill","mcp","model-context-protocol","zerodb","tools","server-development","ai-agents"],"repository":{"type":"git","url":"git+https://github.com/AINative-Studio/ainative-skills.git","directory":"skills/mcp-development"},"author":{"name":"AINative Studio"},"bugs":{"url":"https://github.com/AINative-Studio/ainative-skills/issues"},"license":"MIT","readme":"# @ainative/skill-mcp-development\n\nExpert guidance for building Model Context Protocol (MCP) servers with AINative-specific conventions and ZeroDB integration.\n\n## Installation\n\nInstall the skill package:\n\n```bash\nnpm install @ainative/skill-mcp-development\n```\n\nOr add to your AINative Studio skills directory:\n\n```bash\ncd ~/.ainative/skills\ngit clone https://github.com/ainative/ainative-studio.git\nln -s ainative-studio/skills/mcp-development ./mcp-development\n```\n\n## What This Skill Provides\n\nThis skill extends Anthropic's `mcp-builder` skill with AINative-specific patterns:\n\n- **Naming Conventions**: Kebab-case tool naming standards\n- **Error Handling**: Consistent error response patterns\n- **ZeroDB Integration**: Vector search, upsert, and memory tools\n- **Schema Design**: Zod-based parameter validation\n- **Testing Strategies**: Comprehensive testing patterns\n- **Project Structure**: Standard MCP server layout\n\n## When to Use This Skill\n\nInvoke this skill when:\n\n1. **Creating MCP Servers**: Building new MCP servers from scratch\n2. **Adding Tools**: Implementing new MCP tools\n3. **ZeroDB Integration**: Adding ZeroDB vector search or storage\n4. **Agent Systems**: Building AI agent tool systems\n5. **Testing MCP**: Writing tests for MCP server implementations\n\n## Quick Start\n\n### 1. Create a New MCP Server\n\n```bash\nmkdir my-mcp-server\ncd my-mcp-server\nnpm init -y\nnpm install @modelcontextprotocol/sdk zod\nnpm install -D typescript @types/node\n```\n\n### 2. Basic Server Template\n\n```typescript\n// src/index.ts\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport { z } from 'zod';\n\nconst server = new McpServer({\n  name: 'my-mcp-server',\n  version: '1.0.0',\n});\n\nserver.tool(\n  'example-tool',\n  'Description of what this tool does',\n  {\n    param1: z.string().describe('Parameter description')\n  },\n  async ({ param1 }) => {\n    try {\n      const result = await performOperation(param1);\n      return {\n        content: [{\n          type: \"text\",\n          text: JSON.stringify(result, null, 2)\n        }]\n      };\n    } catch (error) {\n      return {\n        content: [{\n          type: \"text\",\n          text: `Error: ${error instanceof Error ? error.message : String(error)}`\n        }],\n        isError: true\n      };\n    }\n  }\n);\n\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n### 3. Add ZeroDB Integration\n\n```typescript\n// src/tools/search.ts\nimport { z } from 'zod';\nimport { ZeroDBClient } from '../lib/zerodb-client.js';\n\nexport function registerSearchTool(server: McpServer) {\n  server.tool(\n    'zerodb-search',\n    'Search ZeroDB for semantically similar vectors',\n    {\n      table: z.string().describe('Name of the vector table'),\n      query: z.string().describe('Search query text'),\n      top_k: z.number().optional().describe('Number of results (default: 5)')\n    },\n    async ({ table, query, top_k = 5 }) => {\n      try {\n        const client = new ZeroDBClient();\n        const embedding = await generateEmbedding(query);\n        const results = await client.search({ table, vector: embedding, top_k });\n\n        return {\n          content: [{\n            type: \"text\",\n            text: JSON.stringify({\n              query,\n              count: results.length,\n              results\n            }, null, 2)\n          }]\n        };\n      } catch (error) {\n        return {\n          content: [{\n            type: \"text\",\n            text: `Error: ${error instanceof Error ? error.message : String(error)}`\n          }],\n          isError: true\n        };\n      }\n    }\n  );\n}\n```\n\n## Core Principles\n\n### 1. Tool Naming Convention\n\n**ALWAYS use kebab-case** for tool names:\n\n```typescript\n✅ server.tool('zerodb-search', ...);\n✅ server.tool('vector-upsert', ...);\n❌ server.tool('zerodbSearch', ...);\n❌ server.tool('VectorUpsert', ...);\n```\n\n### 2. Error Handling\n\nAll tools must return structured error responses:\n\n```typescript\ntry {\n  const result = await operation();\n  return {\n    content: [{ type: \"text\", text: JSON.stringify(result, null, 2) }]\n  };\n} catch (error) {\n  return {\n    content: [{ type: \"text\", text: `Error: ${error.message}` }],\n    isError: true\n  };\n}\n```\n\n### 3. Schema-First Design\n\nUse Zod schemas with descriptive messages:\n\n```typescript\n{\n  query: z.string().describe('Search query for semantic similarity'),\n  top_k: z.number().optional().describe('Number of results (default: 5)')\n}\n```\n\n## Reference Documentation\n\nDetailed patterns in the `references/` directory:\n\n- **ainative-conventions.md**: AINative-specific MCP patterns\n- **zerodb-integration.md**: ZeroDB tool integration examples\n- **tool-naming.md**: Naming standards and best practices\n- **testing-mcps.md**: Testing strategies for MCP servers\n\n## Example Tools\n\n### Vector Search\n\n```typescript\nserver.tool('zerodb-search', 'Search vectors', schema, async (params) => {\n  const results = await client.search(params);\n  return { content: [{ type: \"text\", text: JSON.stringify(results, null, 2) }] };\n});\n```\n\n### Memory Storage\n\n```typescript\nserver.tool('zerodb-memory-store', 'Store agent memory', schema, async (params) => {\n  await client.upsert({ table: 'memory', vectors: [params] });\n  return { content: [{ type: \"text\", text: \"Memory stored\" }] };\n});\n```\n\n## Testing\n\n```typescript\nimport { describe, it, expect } from '@jest/globals';\n\ndescribe('Search Tool', () => {\n  it('should search successfully', async () => {\n    const result = await searchTool({ table: 'test', query: 'query', top_k: 5 });\n    expect(result.content).toBeDefined();\n  });\n\n  it('should handle errors gracefully', async () => {\n    const result = await searchTool({ table: 'invalid', query: 'query' });\n    expect(result.isError).toBe(true);\n  });\n});\n```\n\n## Environment Variables\n\n```bash\nZERODB_API_KEY=your_api_key\nZERODB_PROJECT_ID=your_project_id\nZERODB_ENDPOINT=https://api.zerodb.io\n```\n\n## Best Practices\n\n1. **Validate input**: Use Zod schemas for type safety\n2. **Provide descriptions**: Help AI understand tool usage\n3. **Handle errors gracefully**: Return structured errors\n4. **Test thoroughly**: Unit, integration, and error path testing\n5. **Use semantic versioning**: Version your servers properly\n\n## Contributing\n\nContributions welcome! Please follow:\n\n- AINative coding standards\n- Kebab-case tool naming\n- 80% test coverage minimum\n- Comprehensive documentation\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Support\n\n- **Documentation**: [AINative Studio Docs](https://docs.ainative.studio)\n- **Issues**: [GitHub Issues](https://github.com/ainative/ainative-studio/issues)\n- **Discord**: [AINative Community](https://discord.gg/ainative)\n\n## Related Skills\n\n- `@ainative/skill-zerodb`: ZeroDB database patterns\n- `@ainative/skill-backend-api`: Backend API development\n- `mcp-builder`: Anthropic's base MCP builder skill\n","readmeFilename":"README.md","_rev":"1-48c64e9e433cae342d008c476253cc4b"}