@hasna/contacts 0.1.0

package/LICENSE

@@ -0,0 +1,180 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is
+      included in or attached to the work (an example is provided
+      in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other
+      transformations represent, as a whole, an original work of authorship.
+      For the purposes of this License, Derivative Works shall not include
+      works that remain separable from, or merely link (or bind by name)
+      to the interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an Individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of documenting and
+      discussing improvements to the Work, but excluding communication that is
+      conspicuously marked or designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) were submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any claim
+      constituting direct or indirect patent infringement, then any patent
+      licenses granted to You under this License for that Work shall
+      terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Work,
+          any patent, copyright, trademark, and other attribution
+          notices from the Source form of the Work, excluding those
+          notices that do not pertain to any part of the Derivative
+          Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You place alongside or in addition to the NOTICE
+          text from the Work, provided that such additional attribution
+          notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional terms and conditions for use, reproduction,
+      or modification of Your Derivative Works, as set forth in Section 6,
+      provided, however, that such additional terms do not contradict the
+      terms of this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any conditions of
+      TITLE, MERCHANTIBILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+      You are solely responsible for determining the appropriateness of
+      using or reproducing the Work and assume any risks associated with
+      Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (even if such Contributor has been advised of the possibility
+      of such damages).
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer only
+      conditions that are consistent with this License and agree that
+      indemnity or any other liability be Your responsibility for any
+      obligations accepted beyond the terms of this License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Andrei Hasna
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,93 @@
+# @hasna/contacts
+
+Contact management for AI coding agents — CLI + MCP server + Web dashboard
+
+A modern rolodex for AI agents and humans. Store contacts, companies, tags, relationships, social profiles, and more.
+
+## Features
+
+- **MCP server** — 24 tools for AI agents (Claude, Codex, Gemini)
+- **CLI** — beautiful terminal interface
+- **Web dashboard** — React/Vite UI
+- **Rich data model** — contacts, companies, tags, relationships, emails, phones, addresses, social profiles
+- **Import/Export** — CSV, vCard (.vcf), JSON
+- **Full-text search** — FTS5-powered search
+- **SQLite** — zero-config, file-based storage at `~/.contacts/contacts.db`
+
+## Install
+
+```bash
+bun install -g @hasna/contacts
+# or
+npm install -g @hasna/contacts
+```
+
+## CLI Usage
+
+```bash
+contacts add                    # Add a contact interactively
+contacts list                   # List all contacts
+contacts list --tag vip         # Filter by tag
+contacts show <id>              # Show contact details
+contacts search "John"          # Search contacts
+contacts edit <id>              # Edit a contact
+contacts delete <id>            # Delete a contact
+contacts import contacts.csv    # Import from CSV/vCard/JSON
+contacts export --format vcf    # Export as vCard
+contacts companies              # List companies
+contacts tags                   # Manage tags
+contacts serve                  # Start web dashboard
+contacts mcp                    # Show MCP setup
+```
+
+## MCP Setup
+
+Add to your Claude Code config:
+```bash
+claude mcp add --transport stdio --scope user contacts -- contacts-mcp
+```
+
+Or add to `~/.claude.json`:
+```json
+{
+  "mcpServers": {
+    "contacts": {
+      "command": "contacts-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_contact` | Create a new contact |
+| `get_contact` | Get contact by ID |
+| `update_contact` | Update contact fields |
+| `delete_contact` | Delete a contact |
+| `list_contacts` | List contacts with filters |
+| `search_contacts` | Full-text search |
+| `create_company` | Create a company |
+| `get_company` | Get company by ID |
+| `list_companies` | List companies |
+| `search_companies` | Search companies |
+| `create_tag` | Create a tag |
+| `list_tags` | List all tags |
+| `add_tag_to_contact` | Tag a contact |
+| `add_relationship` | Link contacts |
+| `merge_contacts` | Merge duplicate contacts |
+| `import_contacts` | Import CSV/vCard/JSON |
+| `export_contacts` | Export contacts |
+| `get_stats` | Get database stats |
+
+## Environment
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONTACTS_DB_PATH` | `~/.contacts/contacts.db` | SQLite database path |
+
+## License
+
+Apache-2.0 © Andrei Hasna