northbid 0.0.0-stage → 0.2.0

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 hexacron
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.
package/README.fr.md ADDED
@@ -0,0 +1,130 @@
1
+ # Northbid
2
+
3
+ [English](README.md) | **Français**
4
+
5
+ Interrogez les données d'approvisionnement du gouvernement du Canada depuis votre assistant IA. Northbid est un serveur local [Model Context Protocol](https://modelcontextprotocol.io) : il charge les données ouvertes publiées par [AchatsCanada](https://achatscanada.canada.ca/fr/donnees-d-approvisionnement-et-d-attribution) dans une petite base de données sur votre ordinateur et donne à l'assistant des outils pour y chercher, en français ou en anglais.
6
+
7
+ Il fonctionne avec Claude Code et Cowork, Codex et l'application de bureau ChatGPT, Gemini CLI et tout autre client capable de lancer un serveur MCP local. Il est gratuit, ne demande aucun compte et n'a aucune dépendance autre que Node.js.
8
+
9
+ > **Non officiel.** Northbid n'est ni affilié au gouvernement du Canada, à AchatsCanada ou à Services publics et Approvisionnement Canada, ni approuvé par eux. Le site AchatsCanada fait foi ; vérifiez-y chaque détail avant de soumissionner.
10
+
11
+ ## Ce que vous pouvez demander
12
+
13
+ - « Quels appels d'offres fédéraux sont ouverts pour des travaux de construction au Québec ? »
14
+ - « Trouve les appels d'offres fédéraux ouverts en services de traduction que je pourrais livrer en Ontario. »
15
+ - « Quelles occasions en sécurité informatique ferment d'ici trois semaines ? Montre les critères de sélection des trois premières. »
16
+ - « Quels fournisseurs détiennent des offres à commandes pour des véhicules légers, et quand expirent-elles ? »
17
+ - « Qui a obtenu les derniers contrats de déneigement à la BFC Petawawa, et pour quel montant ? »
18
+ - « Quels fournisseurs ont obtenu le plus de contrats de traduction depuis avril 2025 ? »
19
+
20
+ ## Ce qui est couvert
21
+
22
+ | Jeu de données | Enregistrements | Mise à jour à la source |
23
+ |---|---|---|
24
+ | Avis d'appel d'offres ouverts | environ 950 | quotidienne, plus les nouveaux avis toutes les 2 heures |
25
+ | Offres à commandes et arrangements en matière d'approvisionnement actifs | environ 4 000 ententes | hebdomadaire |
26
+ | Avis d'attribution depuis août 2022 | environ 30 000 | quotidienne |
27
+
28
+ Organisations fédérales seulement. Les modifications de contrats, les appels d'offres fermés et les archives antérieures à août 2022 figurent sur la [feuille de route](#feuille-de-route). Le schéma et les particularités connues sont décrits dans [docs/data.md](docs/data.md) (en anglais).
29
+
30
+ ## Prérequis
31
+
32
+ Node.js **22.16 ou plus récent** (24 ou plus récent recommandé). Vérifiez avec `node --version`. Node 23 n'est pas pris en charge : son SQLite intégré n'a pas la recherche en texte intégral.
33
+
34
+ ## Installation
35
+
36
+ ### Claude Code et Cowork
37
+
38
+ ```
39
+ /plugin marketplace add hexacron/northbid
40
+ /plugin install northbid@northbid
41
+ ```
42
+
43
+ Le plugiciel ajoute le serveur et une compétence `find-opportunities`. Les serveurs MCP locaux ne s'exécutent pas dans le clavardage claude.ai sur le Web ; vous n'y aurez que la compétence.
44
+
45
+ ### Codex et l'application de bureau ChatGPT
46
+
47
+ ```bash
48
+ git clone https://github.com/hexacron/northbid.git
49
+ codex mcp add northbid -- node /chemin/absolu/vers/northbid/server/index.js
50
+ ```
51
+
52
+ Codex et l'application de bureau ChatGPT partagent cette configuration.
53
+
54
+ ### Gemini CLI
55
+
56
+ ```bash
57
+ gemini extensions install https://github.com/hexacron/northbid
58
+ ```
59
+
60
+ ### Tout autre client MCP
61
+
62
+ Déclarez un serveur stdio qui lance `npx -y northbid`. Le paquet est récupéré depuis npm ; il n'y a rien à cloner :
63
+
64
+ ```json
65
+ {
66
+ "mcpServers": {
67
+ "northbid": { "command": "npx", "args": ["-y", "northbid"] }
68
+ }
69
+ }
70
+ ```
71
+
72
+ Pour l'exécuter à partir des sources, clonez le dépôt et utilisez `node /chemin/absolu/vers/northbid/server/index.js`. [docs/clients.md](docs/clients.md) donne la configuration de chaque client et précise ce qui a été testé.
73
+
74
+ ## Outils
75
+
76
+ | Outil | Ce qu'il fait |
77
+ |---|---|
78
+ | `search_tenders` | Cherche les appels d'offres ouverts par mot-clé, acheteur, catégorie, code UNSPSC, région de livraison et dates |
79
+ | `get_tender` | Fiche complète d'un appel d'offres : description, critères, accords commerciaux, personne-ressource, pièces jointes |
80
+ | `search_standing_offers` | Cherche les offres à commandes et les arrangements en matière d'approvisionnement par mot-clé, fournisseur, ministère, produit |
81
+ | `search_awards` | Cherche les contrats attribués par mot-clé, fournisseur, acheteur, catégorie, code UNSPSC, région, valeur et dates |
82
+ | `get_award` | Fiche complète d'une attribution : fournisseur, valeur, dates du contrat, méthode d'approvisionnement, description |
83
+ | `summarize_awards` | Compte les attributions et additionne leur valeur par fournisseur, acheteur ou année |
84
+ | `data_status` | Indique ce qui est chargé et la date des données |
85
+ | `refresh_data` | Vérifie tout de suite si AchatsCanada a publié des fichiers plus récents |
86
+
87
+ La recherche porte sur le texte français et anglais à la fois et ne tient pas compte des accents : `deneigement` trouve « déneigement ». Passez `lang: "fr"` pour obtenir les résultats en français ; l'assistant le fait de lui-même quand vous lui écrivez en français. Les paramètres et des exemples de résultats sont dans [docs/tools.md](docs/tools.md) (en anglais).
88
+
89
+ ## Ce qu'il fait sur votre ordinateur
90
+
91
+ - **Il télécharge** des fichiers CSV depuis `canadabuys.canada.ca` et `sosa.canadabuys.canada.ca` : trois fichiers, environ 10 Mo au total, à la première utilisation, puis cinq autres, environ 110 Mo au total, la première fois que vous posez une question sur les contrats attribués. Il les revérifie ensuite selon un calendrier et ne télécharge que ce qui a changé. L'un de ces hôtes présente une chaîne de certificats incomplète ; le certificat intermédiaire manquant est donc récupéré à l'adresse indiquée dans le certificat (actuellement `crt.sectigo.com`) et vérifié à l'aide des autorités racines de Node.
92
+ - **Il conserve** les données dans un seul fichier SQLite, dans le répertoire de données du plugiciel ou, hors de Claude, dans le répertoire de cache de votre système d'exploitation. Le fichier atteint environ 165 Mo une fois les attributions chargées. Vous pouvez le supprimer sans risque ; il est reconstruit à la prochaine utilisation.
93
+ - **Il n'envoie rien d'autre.** Vos recherches et vos conversations restent sur votre machine. Il n'y a ni télémétrie ni compte. Voir [PRIVACY.md](PRIVACY.md) (en anglais).
94
+
95
+ Réglages, tous des variables d'environnement facultatives :
96
+
97
+ | Variable | Effet |
98
+ |---|---|
99
+ | `NORTHBID_DATA_DIR` | Emplacement de la base de données |
100
+ | `NORTHBID_OFFLINE=1` | Ne jamais utiliser le réseau ; se servir des données déjà téléchargées |
101
+
102
+ ## Dépannage
103
+
104
+ - **« northbid needs Node.js 22.16 or newer »** : le `node` de votre PATH est trop ancien, ou c'est une version 23.x. Installez une version LTS récente.
105
+ - **« Could not download … »** : le site source était inaccessible. Les recherches continuent avec les dernières données téléchargées et le signalent dans un champ `warnings`. Demandez à l'assistant de lancer `refresh_data` pour réessayer.
106
+ - **Un appel d'offres est absent** : un nouvel avis peut mettre jusqu'à une journée à paraître dans les fichiers de données ouvertes. Consultez `data_status` pour connaître la date des données.
107
+ - **Les heures de clôture** sont données en UTC−05:00 toute l'année, et non à l'heure locale.
108
+ - **Autre chose** : [ouvrez un ticket](https://github.com/hexacron/northbid/issues), en français ou en anglais.
109
+
110
+ ## Feuille de route
111
+
112
+ 1. Historique des contrats avec chaque modification, et téléchargement facultatif des archives depuis 2009.
113
+ 2. Un outil SQL en lecture seule pour les questions que les outils de recherche ne couvrent pas.
114
+ 3. Divulgation proactive des contrats de plus de 10 000 $ de tous les ministères.
115
+
116
+ ## Documentation
117
+
118
+ La documentation détaillée est en anglais.
119
+
120
+ - [docs/clients.md](docs/clients.md) : configuration de chaque client
121
+ - [docs/tools.md](docs/tools.md) : référence des outils
122
+ - [docs/data.md](docs/data.md) : jeux de données, schéma et mises en garde
123
+ - [docs/architecture.md](docs/architecture.md) : architecture
124
+ - [CONTRIBUTING.md](CONTRIBUTING.md) : développement et tests
125
+
126
+ ## Licence et attribution
127
+
128
+ Le code est publié sous la [licence MIT](LICENSE).
129
+
130
+ Contient de l'information visée par la [Licence du gouvernement ouvert – Canada](https://ouvert.canada.ca/fr/licence-du-gouvernement-ouvert-canada). Les données sont publiées par Services publics et Approvisionnement Canada par l'entremise d'AchatsCanada.
package/README.md CHANGED
@@ -1,3 +1,127 @@
1
- # Temporary Holding Version
1
+ # Northbid
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **English** | [Français](README.fr.md)
4
+
5
+ Search Government of Canada procurement data from your AI assistant. Northbid is a local [Model Context Protocol](https://modelcontextprotocol.io) server that loads the open data published by [CanadaBuys](https://canadabuys.canada.ca/en/procurement-and-contracting-data) into a small database on your computer and gives the assistant tools to search it, in English or French.
6
+
7
+ It works with Claude Code and Cowork, Codex and the ChatGPT desktop app, Gemini CLI, and any other client that can run a local MCP server. It is free, needs no account, and has no dependencies beyond Node.js.
8
+
9
+ > **Unofficial.** Northbid is not affiliated with or endorsed by the Government of Canada, CanadaBuys or Public Services and Procurement Canada. The CanadaBuys website is the authoritative source; confirm every detail there before you bid.
10
+
11
+ ## What you can ask
12
+
13
+ - "Find open federal tenders for translation services I could deliver in Ontario."
14
+ - "What IT security opportunities close in the next three weeks? Show the selection criteria for the top three."
15
+ - "Quels appels d'offres fédéraux sont ouverts pour des travaux de construction au Québec ?"
16
+ - "Which suppliers hold standing offers for light duty vehicles, and when do they expire?"
17
+ - "Who won the last snow removal contracts at CFB Petawawa, and for how much?"
18
+ - "Which suppliers won the most translation work since April 2025?"
19
+
20
+ ## What it covers
21
+
22
+ | Dataset | Records | Source refresh |
23
+ |---|---|---|
24
+ | Open tender notices | about 950 | daily, plus new notices every 2 hours |
25
+ | Active standing offers and supply arrangements | about 4,000 agreements | weekly |
26
+ | Award notices since August 2022 | about 30,000 | daily |
27
+
28
+ Federal organizations only. Contract amendments, closed tenders and the archives before August 2022 are on the [roadmap](#roadmap). See [docs/data.md](docs/data.md) for the schema and known quirks.
29
+
30
+ ## Requirements
31
+
32
+ Node.js **22.16 or newer** (24 or newer recommended). Check with `node --version`. Node 23 is not supported because its built-in SQLite lacks full-text search.
33
+
34
+ ## Install
35
+
36
+ ### Claude Code and Cowork
37
+
38
+ ```
39
+ /plugin marketplace add hexacron/northbid
40
+ /plugin install northbid@northbid
41
+ ```
42
+
43
+ The plugin adds the server and a `find-opportunities` skill. Local MCP servers do not run in claude.ai chat on the web; there you get the skill only.
44
+
45
+ ### Codex and the ChatGPT desktop app
46
+
47
+ ```bash
48
+ git clone https://github.com/hexacron/northbid.git
49
+ codex mcp add northbid -- node /absolute/path/to/northbid/server/index.js
50
+ ```
51
+
52
+ Codex and the ChatGPT desktop app share this configuration.
53
+
54
+ ### Gemini CLI
55
+
56
+ ```bash
57
+ gemini extensions install https://github.com/hexacron/northbid
58
+ ```
59
+
60
+ ### Any other MCP client
61
+
62
+ Register a stdio server that runs `npx -y northbid`. This fetches the package from npm, so there is nothing to clone:
63
+
64
+ ```json
65
+ {
66
+ "mcpServers": {
67
+ "northbid": { "command": "npx", "args": ["-y", "northbid"] }
68
+ }
69
+ }
70
+ ```
71
+
72
+ To run from source instead, clone the repository and use `node /absolute/path/to/northbid/server/index.js`. [docs/clients.md](docs/clients.md) has the configuration for each client and notes on what has been tested.
73
+
74
+ ## Tools
75
+
76
+ | Tool | What it does |
77
+ |---|---|
78
+ | `search_tenders` | Search open tenders by keyword, buyer, category, UNSPSC code, delivery region and dates |
79
+ | `get_tender` | Full record for one tender: description, criteria, trade agreements, contact, attachments |
80
+ | `search_standing_offers` | Search standing offers and supply arrangements by keyword, supplier, department, commodity |
81
+ | `search_awards` | Search contract awards by keyword, supplier, buyer, category, UNSPSC code, region, value and dates |
82
+ | `get_award` | Full record for an award: supplier, value, contract dates, procurement method, description |
83
+ | `summarize_awards` | Count awards and total their value by supplier, buyer or year |
84
+ | `data_status` | Show what is loaded and how current it is |
85
+ | `refresh_data` | Check CanadaBuys for newer files now |
86
+
87
+ Search matches English and French text at once and ignores accents. Full parameters and sample output are in [docs/tools.md](docs/tools.md).
88
+
89
+ ## What it does on your computer
90
+
91
+ - **Downloads** CSV files from `canadabuys.canada.ca` and `sosa.canadabuys.canada.ca`: three files of about 10 MB in total on first use, and five more of about 110 MB in total the first time you ask about contract awards. It then re-checks them on a schedule and downloads only what changed. One of those hosts serves an incomplete certificate chain, so the missing issuer certificate is fetched from the address named in the certificate (currently `crt.sectigo.com`) and verified against Node's trusted roots.
92
+ - **Stores** the data in one SQLite file in the plugin's data directory, or your operating system's cache directory when run outside Claude. It grows to about 165 MB once awards are loaded. Deleting the file is safe; it is rebuilt on next use.
93
+ - **Sends nothing else.** Your searches and conversations stay on your machine. There is no telemetry and no account. See [PRIVACY.md](PRIVACY.md).
94
+
95
+ Settings, all optional environment variables:
96
+
97
+ | Variable | Effect |
98
+ |---|---|
99
+ | `NORTHBID_DATA_DIR` | Where to keep the database |
100
+ | `NORTHBID_OFFLINE=1` | Never contact the network; use the data already downloaded |
101
+
102
+ ## Troubleshooting
103
+
104
+ - **"northbid needs Node.js 22.16 or newer"**: the `node` on your PATH is too old, or is a 23.x release. Install a current LTS release.
105
+ - **"Could not download …"**: the source site was unreachable. Searches keep working on the last downloaded data and say so in a `warnings` field. Ask the assistant to run `refresh_data` to retry.
106
+ - **A tender is missing**: new notices can take up to a day to reach the open data files. Check `data_status` for the data date.
107
+ - **Something else**: [open an issue](https://github.com/hexacron/northbid/issues).
108
+
109
+ ## Roadmap
110
+
111
+ 1. Contract history with every amendment, and optional download of the archives back to 2009.
112
+ 2. A read-only SQL tool for questions the search tools do not cover.
113
+ 3. Proactive disclosure of contracts over $10,000 from all departments.
114
+
115
+ ## Documentation
116
+
117
+ - [docs/clients.md](docs/clients.md): setup for each client
118
+ - [docs/tools.md](docs/tools.md): tool reference
119
+ - [docs/data.md](docs/data.md): datasets, schema and caveats
120
+ - [docs/architecture.md](docs/architecture.md): how it is built
121
+ - [CONTRIBUTING.md](CONTRIBUTING.md): development and tests
122
+
123
+ ## Licence and attribution
124
+
125
+ Code is released under the [MIT licence](LICENSE).
126
+
127
+ Contains information licensed under the [Open Government Licence – Canada](https://open.canada.ca/en/open-government-licence-canada). The data is published by Public Services and Procurement Canada through CanadaBuys.
package/package.json CHANGED
@@ -1,6 +1,34 @@
1
1
  {
2
2
  "name": "northbid",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "mcpName": "io.github.hexacron/northbid",
5
+ "description": "Search Government of Canada procurement data (CanadaBuys) from any MCP client. Unofficial.",
6
+ "type": "module",
7
+ "bin": {
8
+ "northbid": "server/index.js"
9
+ },
10
+ "files": [
11
+ "server"
12
+ ],
13
+ "scripts": {
14
+ "start": "node server/index.js",
15
+ "test": "node --test"
16
+ },
17
+ "engines": {
18
+ "node": "^22.16.0 || >=24.0.0"
19
+ },
20
+ "keywords": [
21
+ "mcp",
22
+ "canada",
23
+ "procurement",
24
+ "canadabuys",
25
+ "tenders",
26
+ "government"
27
+ ],
28
+ "homepage": "https://github.com/hexacron/northbid",
29
+ "repository": {
30
+ "type": "git",
31
+ "url": "git+https://github.com/hexacron/northbid.git"
32
+ },
33
+ "license": "MIT"
34
+ }
package/server/csv.js ADDED
@@ -0,0 +1,88 @@
1
+ // Streaming RFC 4180 parser. Fields may contain quoted commas, quotes ("") and
2
+ // newlines; input arrives as arbitrary string chunks.
3
+
4
+ /**
5
+ * @param {AsyncIterable<string> | Iterable<string>} chunks
6
+ * @returns {AsyncGenerator<string[]>} one array of fields per record
7
+ */
8
+ export async function* parseCsv(chunks) {
9
+ let carry = '';
10
+ let field = '';
11
+ let row = [];
12
+ let inQuotes = false;
13
+ let first = true;
14
+
15
+ // Consumes `text`; when not `final`, stops before a trailing `"` or `\r`
16
+ // whose meaning depends on the next chunk and leaves it in `carry`.
17
+ function* consume(text, final) {
18
+ const n = text.length;
19
+ let i = 0;
20
+ let start = 0;
21
+ while (i < n) {
22
+ const c = text.charCodeAt(i);
23
+ if (inQuotes) {
24
+ if (c !== 34) { i++; continue; }
25
+ if (i + 1 === n && !final) break;
26
+ field += text.slice(start, i);
27
+ if (text.charCodeAt(i + 1) === 34) { field += '"'; i += 2; } else { inQuotes = false; i++; }
28
+ start = i;
29
+ } else if (c === 34) {
30
+ field += text.slice(start, i);
31
+ inQuotes = true;
32
+ start = ++i;
33
+ } else if (c === 44) {
34
+ row.push(field + text.slice(start, i));
35
+ field = '';
36
+ start = ++i;
37
+ } else if (c === 10 || c === 13) {
38
+ if (c === 13 && i + 1 === n && !final) break;
39
+ row.push(field + text.slice(start, i));
40
+ field = '';
41
+ i += c === 13 && text.charCodeAt(i + 1) === 10 ? 2 : 1;
42
+ start = i;
43
+ yield row;
44
+ row = [];
45
+ } else {
46
+ i++;
47
+ }
48
+ }
49
+ field += text.slice(start, i);
50
+ carry = text.slice(i);
51
+ }
52
+
53
+ for await (let chunk of chunks) {
54
+ if (first) {
55
+ first = false;
56
+ if (chunk.charCodeAt(0) === 0xfeff) chunk = chunk.slice(1);
57
+ }
58
+ yield* consume(carry + chunk, false);
59
+ }
60
+ yield* consume(carry, true);
61
+ if (field !== '' || row.length > 0) {
62
+ row.push(field);
63
+ yield row;
64
+ }
65
+ }
66
+
67
+ /**
68
+ * Reads a CSV with a header row and yields one accessor per record. The
69
+ * accessor throws on an unknown column so an upstream format change fails
70
+ * loudly instead of loading blanks.
71
+ * @param {AsyncIterable<string> | Iterable<string>} chunks
72
+ * @returns {AsyncGenerator<(column: string) => string>}
73
+ */
74
+ export async function* records(chunks) {
75
+ let index = null;
76
+ for await (const row of parseCsv(chunks)) {
77
+ if (!index) {
78
+ index = new Map(row.map((name, i) => [name.trim(), i]));
79
+ continue;
80
+ }
81
+ if (row.length === 1 && row[0] === '') continue;
82
+ yield (column) => {
83
+ const i = index.get(column);
84
+ if (i === undefined) throw new Error(`source file has no "${column}" column; its format may have changed`);
85
+ return row[i] ?? '';
86
+ };
87
+ }
88
+ }