{"id":13566835,"url":"https://github.com/contextprotocol/sdk","last_synced_at":"2025-04-04T00:32:20.907Z","repository":{"id":239599988,"uuid":"784668952","full_name":"contextprotocol/sdk","owner":"contextprotocol","description":"The Context SDK provides a powerful and flexible way to interact with Context, enabling developers to manage domains and documents programmatically.","archived":false,"fork":false,"pushed_at":"2024-11-06T14:14:56.000Z","size":332,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-11T03:08:26.388Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.ctx.xyz","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/contextprotocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-10T10:08:28.000Z","updated_at":"2024-06-14T16:50:51.000Z","dependencies_parsed_at":"2024-05-13T15:11:12.341Z","dependency_job_id":"c9e94bf7-6e58-4f8c-b896-e41ad583c835","html_url":"https://github.com/contextprotocol/sdk","commit_stats":null,"previous_names":["contextprotocol/sdk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contextprotocol%2Fsdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contextprotocol%2Fsdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contextprotocol%2Fsdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contextprotocol%2Fsdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/contextprotocol","download_url":"https://codeload.github.com/contextprotocol/sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247103290,"owners_count":20884023,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T13:02:17.713Z","updated_at":"2025-04-04T00:32:20.446Z","avatar_url":"https://github.com/contextprotocol.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\n# Context SDK\n![](./assets/context-sdk.png?raw=true)\n\n\nThe [Context SDK](http://docs.ctx.xyz) is a robust and flexible toolkit designed for developers to interact programmatically with [Context Protocol](https://ctx.xyz).\n\n## What is Context\nContext is an abstraction layer designed to integrate Web3 storage technologies, providing distinctive features that enhance data management. Dive into creation with our SDK, which helps users to **organize, read and share public and private data** in a sovereign, trusted and verified way. Saying goodbye to hashes, and embracing domains and documents within the blockchain ecosystem. We empower developers to innovate, providing the tools you need to build groundbreaking applications on top of our platform. \n\nEvery data on Context is publicly available, free, and forever for other developers to use everywhere through our public gateway - i.e. [rpc.ctx.xyz/contextprotocol](https://rpc.ctx.xyz/contextprotocol)\n\n### How it works\n- **Domains** → Domains represent verified and curated entities, such as companies, projects, or products.\n- **Documents** → Context Documents are files designed to store and organize JSON data. Each Document serves as a repository for specific sets of information, facilitating efficient data management and retrieval.\n- **Templates** → Context Templates help organize data by providing a standardized layout for storing information. With them, you can easily create, share, and utilize consistent data structures.\n- **Assets** → Context Assets are designed to store and organize any image or file. Each Asset serves as a source for specific data, facilitating efficient data management and retrieval.  \n\u003cbr /\u003e\n\n![](./assets/whats-context.png?raw=true)\n\n*Poolside, Context and Alex as Domains, with Documents inside that contain relations between them. The Template \"web3/token\" used on the \"context/token\" Document.*\n\n### Why use Context?\nContext Protocol is a Web3 Semantic Layer that brings your data:\n\n- **Sovereignty** On Context you control your Data, no third parties involved.\n- **Verified Data \u0026 Traceability** Get information accuracy verification through our semantic layer, ensuring trust and reliability.\n- **Structured Data Storage** Say goodbye to chaotic data storage! Context offers a structured approach to organizing your data using industry-standard templates on top of web3. \n- **AI Empowerment** Context ensures that AI models are trained with structured and verified data, enhancing overall AI performance. \n- **Brand Control** enabling real-time synchronization of your data ensuring updates are promptly propagated across all platforms and partners.\n- **Security Data** is stored on the blockchain.\n\n\u003cbr /\u003e\n\n## ⚡ Getting started\n### Install the SDK\nInstall the Context SDK to your TypeScript project using npm:\n\n```bash\nnpm install @contextprotocol/sdk\n```\n\n### Setting Up Your Connection\nTo use Context, you always need a domain. This domain acts as your namespace within Context, where all your documents will be stored. Then, you'll need to obtain an API key for your domain.\n\nYou can claim your domain and generate the API key by creating an account at [app.ctx.xyz](https://app.ctx.xyz).\n\nInitialize the SDK:\n\n```typescript\nimport { Context } from '@contextprotocol/sdk';\n\nconst ctx = new Context({ apiKey: \"your_api_key_here\" }); // Replace with your API key\n```\n\n\n\u003cbr /\u003e\n\n## 🌐 Working with Domains\nDomains represent verified and curated entities, such as companies, projects, or individuals.\n\n\n### Fetch Domain Information\nFetch details of a specific domain or the default domain associated with your API key:\n\n```typescript\n// Fetch your domain\nconst yourDomain = await ctx.domain();\n\n// Fetch a specific domain\nconst domain = await ctx.domain(\"domain_name\");\n```\n\n### Domain Properties\nAccess and display properties of a domain:\n\n```typescript\nconsole.log(domain.data.name);\nconsole.log(domain.data.documents);\nconsole.log(domain.data.status);\nconsole.log(domain.data.createdAt);\nconsole.log(domain.data.updatedAt);\n```\n\n\n\u003cbr /\u003e\n\n## 📄 Managing Documents\n\n\n### Fetch Documents\nFetch a specific document or template or asset, from any domain:\n\n```typescript\n// Fetch a specific document\nconst document = await ctx.document(\"document_path\");  // \"domain/path/to/file\"\n```\n\n### Document Properties\nAccess and display properties of a document:\n\n```typescript\nconsole.log(document.data.path);\nconsole.log(document.data.versionNumber);\nconsole.log(document.data.data);\nconsole.log(document.data.metadata);\nconsole.log(document.data.templates);\nconsole.log(document.data.type); // Document | Template | Asset\nconsole.log(document.data.txId);\nconsole.log(document.data.createdAt);\nconsole.log(document.data.updatedAt);\nconsole.log(JSON.stringify(document.data));\n```\n\n### List Document Versions\nFetch a list of all versions of a document:\n\n```typescript\nconst documentVersions = await document.data.versions();\n```\n\n### Fetch a Specific Document Version\nYou can fetch a specific version of a document in two different ways:\n\n```typescript\n// By using the version method of the document:\nconst document = await ctx.document(\"document_path\");\nconst documentVersion = await document.data.getVersion(\"X.Y.Z\");\n\n// By specifying the version directly the document path:\nconst documentInVersionXYZ = await ctx.document(\"document_path?v=X.Y.Z\");\n```\n\n### Create a Document\nSteps to create a new document within your domain:\n\n```typescript\nconst data = YOUR_AWESOME_JSON_DATA;  // JSON data for the document\nconst templates = [\"template_path\"];  // Optional array of template paths\nconst metadata = { name: \"Document Name\", description: \"Document Description\", readme: \"ctx:domain/files/my_markdown\" };  // Optional metadata\n\nconst newDocument = await ctx.createDocument(\"document_path\", data, templates, metadata);\n```\n\n### Update a Document\nUpdate an existing document:\n\n```typescript\nconst updatedData = YOUR_UPDATED_AWESOME_JSON_DATA;  // Updated JSON data\nconst document = await ctx.document(\"document_path\");\nif (!document.success) {\n    // Handle error\n}\nconst result = await document.data.update(updatedData);\n```\n\n### Adding Metadata to a Document\nYou can add/update metadata to a document anytime using the `addMetadata` method. The metadata object should contain the following (optional) fields: `name`, `description`, and `readme` (link to a Markdown document) as shown below:\n\n```typescript\nconst metadata = { name: \"Document Name\", description: \"Document Description\", readme: \"ctx:domain/files/my_markdown\" };\nawait document.data.addMetadata(metadata);\n```\n\n\u003cbr /\u003e\n\n## 📐 Creating Templates\n\n\n### Define a JSON Schema for a Template\nCreate a JSON schema directly or from a TypeScript interface:\n\n```typescript\n// Direct JSON Schema definition\nconst schema = {\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\"type\": \"string\", \"description\": \"The name of the organization.\"},\n    \"description\": {\"type\": \"string\", \"description\": \"A brief description of the organization.\"},\n    \"website\": {\"type\": \"string\", \"description\": \"The URL of the organization's website.\", \"format\": \"uri\"}\n  },\n  \"required\": [\"name\"],\n};\n\n// Generate JSON schema from a TypeScript interface\nconst dataName = 'User';\nconst myDataType = `interface ${dataName} {\n  name: string;\n  age: number;\n}`;\nconst schema = generateJsonSchema(dataName, myDataType);\n```\n\n### Create a New Template\nUse the defined schema to create a new template:\n\n```typescript\nconst template = await ctx.createTemplate(\"template_path\", schema);\n```\n### Installing Templates\nOnce we have the template, we can install it in a document by using the `install` method:\n```typescript\nconst document = await ctx.document(\"document_path\");\nif (!document.success) {\n    // Handle error\n}\nconst templateArrayToInstall = [\"template_path\"];\nconst newDoc = await document.data.install(templateArrayToInstall);\n```\n### Uninstalling Templates\nTo uninstall a template from a document, we can use the `uninstall` method:\n```typescript\nconst document = await ctx.document(\"document_path\");\nif (!document.success) {\n    // Handle error\n}\nconst templateArrayToUninstall = [\"template_path\"];\nconst newDoc = await document.data.uninstall(templateArrayToUninstall);\n```\n\n\u003cbr /\u003e\n\n## 📦 Assets\n\n### Upload new Assets\nAs a user, you can upload assets to your domain. When uploading an asset, you can specify the document path where the asset will be stored.\n\n```typescript\nconst ctxDocumentPath = \"document/path\";\nconst localFilePath = \"file/path.jpg\";\nconst asset = await ctx.createAsset(ctxDocumentPath, localFilePath, metadata /* optional */);\n```\n\n### Update an Asset\nYou can update an existing asset by providing the document path and the local file path of the updated asset. It returns a document with a new version.\n\n```typescript\nconst localFilePath = \"file/path.jpg\";\nconst asset = await document.data.updateAsset(localFilePath, metadata /* optional */);\n```\n\n\n## 👨‍🔧 Error Handling\nWhen calling a function, you can check if an error occurred by checking the `error` property in the returned object:\n\n```typescript\nconst document = await ctx.document(\"document_path\");\nif(document.success === false){\n  console.error(document.error.error); // Error message\n  console.error(document.error.message); // Detailed error message\n  console.error(document.error.statusCode); // HTTP status code\n}\n```\n\n\n## Support\nIf you have any questions or just want to brainstorm about how to integrate Context into your project, reach out to us on [Telegram](https://t.me/contextdao) or by [email](mailto:support@ctx.xyz).\n\n\nFor more detailed information and examples, visit the [official Context SDK documentation](https://docs.ctx.xyz).\n\n## License\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontextprotocol%2Fsdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcontextprotocol%2Fsdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontextprotocol%2Fsdk/lists"}